xref: /openbmc/qemu/hw/sensor/lsm303dlhc_mag.c (revision 28ae3179fc52d2e4d870b635c4a412aab99759e7)
1  /*
2   * LSM303DLHC I2C magnetometer.
3   *
4   * Copyright (C) 2021 Linaro Ltd.
5   * Written by Kevin Townsend <kevin.townsend@linaro.org>
6   *
7   * Based on: https://www.st.com/resource/en/datasheet/lsm303dlhc.pdf
8   *
9   * SPDX-License-Identifier: GPL-2.0-or-later
10   */
11  
12  /*
13   * The I2C address associated with this device is set on the command-line when
14   * initialising the machine, but the following address is standard: 0x1E.
15   *
16   * Get and set functions for 'mag-x', 'mag-y' and 'mag-z' assume that
17   * 1 = 0.001 uT. (NOTE the 1 gauss = 100 uT, so setting a value of 100,000
18   * would be equal to 1 gauss or 100 uT.)
19   *
20   * Get and set functions for 'temperature' assume that 1 = 0.001 C, so 23.6 C
21   * would be equal to 23600.
22   */
23  
24  #include "qemu/osdep.h"
25  #include "hw/i2c/i2c.h"
26  #include "migration/vmstate.h"
27  #include "qapi/error.h"
28  #include "qapi/visitor.h"
29  #include "qemu/module.h"
30  #include "qemu/log.h"
31  #include "qemu/bswap.h"
32  
33  enum LSM303DLHCMagReg {
34      LSM303DLHC_MAG_REG_CRA          = 0x00,
35      LSM303DLHC_MAG_REG_CRB          = 0x01,
36      LSM303DLHC_MAG_REG_MR           = 0x02,
37      LSM303DLHC_MAG_REG_OUT_X_H      = 0x03,
38      LSM303DLHC_MAG_REG_OUT_X_L      = 0x04,
39      LSM303DLHC_MAG_REG_OUT_Z_H      = 0x05,
40      LSM303DLHC_MAG_REG_OUT_Z_L      = 0x06,
41      LSM303DLHC_MAG_REG_OUT_Y_H      = 0x07,
42      LSM303DLHC_MAG_REG_OUT_Y_L      = 0x08,
43      LSM303DLHC_MAG_REG_SR           = 0x09,
44      LSM303DLHC_MAG_REG_IRA          = 0x0A,
45      LSM303DLHC_MAG_REG_IRB          = 0x0B,
46      LSM303DLHC_MAG_REG_IRC          = 0x0C,
47      LSM303DLHC_MAG_REG_TEMP_OUT_H   = 0x31,
48      LSM303DLHC_MAG_REG_TEMP_OUT_L   = 0x32
49  };
50  
51  typedef struct LSM303DLHCMagState {
52      I2CSlave parent_obj;
53      uint8_t cra;
54      uint8_t crb;
55      uint8_t mr;
56      int16_t x;
57      int16_t z;
58      int16_t y;
59      int16_t x_lock;
60      int16_t z_lock;
61      int16_t y_lock;
62      uint8_t sr;
63      uint8_t ira;
64      uint8_t irb;
65      uint8_t irc;
66      int16_t temperature;
67      int16_t temperature_lock;
68      uint8_t len;
69      uint8_t buf;
70      uint8_t pointer;
71  } LSM303DLHCMagState;
72  
73  #define TYPE_LSM303DLHC_MAG "lsm303dlhc_mag"
74  OBJECT_DECLARE_SIMPLE_TYPE(LSM303DLHCMagState, LSM303DLHC_MAG)
75  
76  /*
77   * Conversion factor from Gauss to sensor values for each GN gain setting,
78   * in units "lsb per Gauss" (see data sheet table 3). There is no documented
79   * behaviour if the GN setting in CRB is incorrectly set to 0b000;
80   * we arbitrarily make it the same as 0b001.
81   */
82  uint32_t xy_gain[] = { 1100, 1100, 855, 670, 450, 400, 330, 230 };
83  uint32_t z_gain[] = { 980, 980, 760, 600, 400, 355, 295, 205 };
84  
lsm303dlhc_mag_get_x(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)85  static void lsm303dlhc_mag_get_x(Object *obj, Visitor *v, const char *name,
86                                   void *opaque, Error **errp)
87  {
88      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
89      int gm = extract32(s->crb, 5, 3);
90  
91      /* Convert to uT where 1000 = 1 uT. Conversion factor depends on gain. */
92      int64_t value = muldiv64(s->x, 100000, xy_gain[gm]);
93      visit_type_int(v, name, &value, errp);
94  }
95  
lsm303dlhc_mag_get_y(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)96  static void lsm303dlhc_mag_get_y(Object *obj, Visitor *v, const char *name,
97                                   void *opaque, Error **errp)
98  {
99      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
100      int gm = extract32(s->crb, 5, 3);
101  
102      /* Convert to uT where 1000 = 1 uT. Conversion factor depends on gain. */
103      int64_t value = muldiv64(s->y, 100000, xy_gain[gm]);
104      visit_type_int(v, name, &value, errp);
105  }
106  
lsm303dlhc_mag_get_z(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)107  static void lsm303dlhc_mag_get_z(Object *obj, Visitor *v, const char *name,
108                                   void *opaque, Error **errp)
109  {
110      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
111      int gm = extract32(s->crb, 5, 3);
112  
113      /* Convert to uT where 1000 = 1 uT. Conversion factor depends on gain. */
114      int64_t value = muldiv64(s->z, 100000, z_gain[gm]);
115      visit_type_int(v, name, &value, errp);
116  }
117  
lsm303dlhc_mag_set_x(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)118  static void lsm303dlhc_mag_set_x(Object *obj, Visitor *v, const char *name,
119                                   void *opaque, Error **errp)
120  {
121      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
122      int64_t value;
123      int64_t reg;
124      int gm = extract32(s->crb, 5, 3);
125  
126      if (!visit_type_int(v, name, &value, errp)) {
127          return;
128      }
129  
130      reg = muldiv64(value, xy_gain[gm], 100000);
131  
132      /* Make sure we are within a 12-bit limit. */
133      if (reg > 2047 || reg < -2048) {
134          error_setg(errp, "value %" PRId64 " out of register's range", value);
135          return;
136      }
137  
138      s->x = (int16_t)reg;
139  }
140  
lsm303dlhc_mag_set_y(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)141  static void lsm303dlhc_mag_set_y(Object *obj, Visitor *v, const char *name,
142                                   void *opaque, Error **errp)
143  {
144      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
145      int64_t value;
146      int64_t reg;
147      int gm = extract32(s->crb, 5, 3);
148  
149      if (!visit_type_int(v, name, &value, errp)) {
150          return;
151      }
152  
153      reg = muldiv64(value, xy_gain[gm], 100000);
154  
155      /* Make sure we are within a 12-bit limit. */
156      if (reg > 2047 || reg < -2048) {
157          error_setg(errp, "value %" PRId64 " out of register's range", value);
158          return;
159      }
160  
161      s->y = (int16_t)reg;
162  }
163  
lsm303dlhc_mag_set_z(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)164  static void lsm303dlhc_mag_set_z(Object *obj, Visitor *v, const char *name,
165                                   void *opaque, Error **errp)
166  {
167      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
168      int64_t value;
169      int64_t reg;
170      int gm = extract32(s->crb, 5, 3);
171  
172      if (!visit_type_int(v, name, &value, errp)) {
173          return;
174      }
175  
176      reg = muldiv64(value, z_gain[gm], 100000);
177  
178      /* Make sure we are within a 12-bit limit. */
179      if (reg > 2047 || reg < -2048) {
180          error_setg(errp, "value %" PRId64 " out of register's range", value);
181          return;
182      }
183  
184      s->z = (int16_t)reg;
185  }
186  
187  /*
188   * Get handler for the temperature property.
189   */
lsm303dlhc_mag_get_temperature(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)190  static void lsm303dlhc_mag_get_temperature(Object *obj, Visitor *v,
191                                             const char *name, void *opaque,
192                                             Error **errp)
193  {
194      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
195      int64_t value;
196  
197      /* Convert to 1 lsb = 0.125 C to 1 = 0.001 C for 'temperature' property. */
198      value = s->temperature * 125;
199  
200      visit_type_int(v, name, &value, errp);
201  }
202  
203  /*
204   * Set handler for the temperature property.
205   */
lsm303dlhc_mag_set_temperature(Object * obj,Visitor * v,const char * name,void * opaque,Error ** errp)206  static void lsm303dlhc_mag_set_temperature(Object *obj, Visitor *v,
207                                             const char *name, void *opaque,
208                                             Error **errp)
209  {
210      LSM303DLHCMagState *s = LSM303DLHC_MAG(obj);
211      int64_t value;
212  
213      if (!visit_type_int(v, name, &value, errp)) {
214          return;
215      }
216  
217      /* Input temperature is in 0.001 C units. Convert to 1 lsb = 0.125 C. */
218      value /= 125;
219  
220      if (value > 2047 || value < -2048) {
221          error_setg(errp, "value %" PRId64 " lsb is out of range", value);
222          return;
223      }
224  
225      s->temperature = (int16_t)value;
226  }
227  
228  /*
229   * Callback handler whenever a 'I2C_START_RECV' (read) event is received.
230   */
lsm303dlhc_mag_read(LSM303DLHCMagState * s)231  static void lsm303dlhc_mag_read(LSM303DLHCMagState *s)
232  {
233      /*
234       * Set the LOCK bit whenever a new read attempt is made. This will be
235       * cleared in I2C_FINISH. Note that DRDY is always set to 1 in this driver.
236       */
237      s->sr = 0x3;
238  
239      /*
240       * Copy the current X/Y/Z and temp. values into the locked registers so
241       * that 'mag-x', 'mag-y', 'mag-z' and 'temperature' can continue to be
242       * updated via QOM, etc., without corrupting the current read event.
243       */
244      s->x_lock = s->x;
245      s->z_lock = s->z;
246      s->y_lock = s->y;
247      s->temperature_lock = s->temperature;
248  }
249  
250  /*
251   * Callback handler whenever a 'I2C_FINISH' event is received.
252   */
lsm303dlhc_mag_finish(LSM303DLHCMagState * s)253  static void lsm303dlhc_mag_finish(LSM303DLHCMagState *s)
254  {
255      /*
256       * Clear the LOCK bit when the read attempt terminates.
257       * This bit is initially set in the I2C_START_RECV handler.
258       */
259      s->sr = 0x1;
260  }
261  
262  /*
263   * Callback handler when a device attempts to write to a register.
264   */
lsm303dlhc_mag_write(LSM303DLHCMagState * s)265  static void lsm303dlhc_mag_write(LSM303DLHCMagState *s)
266  {
267      switch (s->pointer) {
268      case LSM303DLHC_MAG_REG_CRA:
269          s->cra = s->buf;
270          break;
271      case LSM303DLHC_MAG_REG_CRB:
272          /* Make sure gain is at least 1, falling back to 1 on an error. */
273          if (s->buf >> 5 == 0) {
274              s->buf = 1 << 5;
275          }
276          s->crb = s->buf;
277          break;
278      case LSM303DLHC_MAG_REG_MR:
279          s->mr = s->buf;
280          break;
281      case LSM303DLHC_MAG_REG_SR:
282          s->sr = s->buf;
283          break;
284      case LSM303DLHC_MAG_REG_IRA:
285          s->ira = s->buf;
286          break;
287      case LSM303DLHC_MAG_REG_IRB:
288          s->irb = s->buf;
289          break;
290      case LSM303DLHC_MAG_REG_IRC:
291          s->irc = s->buf;
292          break;
293      default:
294          qemu_log_mask(LOG_GUEST_ERROR, "reg is read-only: 0x%02X", s->buf);
295          break;
296      }
297  }
298  
299  /*
300   * Low-level master-to-slave transaction handler.
301   */
lsm303dlhc_mag_send(I2CSlave * i2c,uint8_t data)302  static int lsm303dlhc_mag_send(I2CSlave *i2c, uint8_t data)
303  {
304      LSM303DLHCMagState *s = LSM303DLHC_MAG(i2c);
305  
306      if (s->len == 0) {
307          /* First byte is the reg pointer */
308          s->pointer = data;
309          s->len++;
310      } else if (s->len == 1) {
311          /* Second byte is the new register value. */
312          s->buf = data;
313          lsm303dlhc_mag_write(s);
314      } else {
315          g_assert_not_reached();
316      }
317  
318      return 0;
319  }
320  
321  /*
322   * Low-level slave-to-master transaction handler (read attempts).
323   */
lsm303dlhc_mag_recv(I2CSlave * i2c)324  static uint8_t lsm303dlhc_mag_recv(I2CSlave *i2c)
325  {
326      LSM303DLHCMagState *s = LSM303DLHC_MAG(i2c);
327      uint8_t resp;
328  
329      switch (s->pointer) {
330      case LSM303DLHC_MAG_REG_CRA:
331          resp = s->cra;
332          break;
333      case LSM303DLHC_MAG_REG_CRB:
334          resp = s->crb;
335          break;
336      case LSM303DLHC_MAG_REG_MR:
337          resp = s->mr;
338          break;
339      case LSM303DLHC_MAG_REG_OUT_X_H:
340          resp = (uint8_t)(s->x_lock >> 8);
341          break;
342      case LSM303DLHC_MAG_REG_OUT_X_L:
343          resp = (uint8_t)(s->x_lock);
344          break;
345      case LSM303DLHC_MAG_REG_OUT_Z_H:
346          resp = (uint8_t)(s->z_lock >> 8);
347          break;
348      case LSM303DLHC_MAG_REG_OUT_Z_L:
349          resp = (uint8_t)(s->z_lock);
350          break;
351      case LSM303DLHC_MAG_REG_OUT_Y_H:
352          resp = (uint8_t)(s->y_lock >> 8);
353          break;
354      case LSM303DLHC_MAG_REG_OUT_Y_L:
355          resp = (uint8_t)(s->y_lock);
356          break;
357      case LSM303DLHC_MAG_REG_SR:
358          resp = s->sr;
359          break;
360      case LSM303DLHC_MAG_REG_IRA:
361          resp = s->ira;
362          break;
363      case LSM303DLHC_MAG_REG_IRB:
364          resp = s->irb;
365          break;
366      case LSM303DLHC_MAG_REG_IRC:
367          resp = s->irc;
368          break;
369      case LSM303DLHC_MAG_REG_TEMP_OUT_H:
370          /* Check if the temperature sensor is enabled or not (CRA & 0x80). */
371          if (s->cra & 0x80) {
372              resp = (uint8_t)(s->temperature_lock >> 8);
373          } else {
374              resp = 0;
375          }
376          break;
377      case LSM303DLHC_MAG_REG_TEMP_OUT_L:
378          if (s->cra & 0x80) {
379              resp = (uint8_t)(s->temperature_lock & 0xff);
380          } else {
381              resp = 0;
382          }
383          break;
384      default:
385          resp = 0;
386          break;
387      }
388  
389      /*
390       * The address pointer on the LSM303DLHC auto-increments whenever a byte
391       * is read, without the master device having to request the next address.
392       *
393       * The auto-increment process has the following logic:
394       *
395       *   - if (s->pointer == 8) then s->pointer = 3
396       *   - else: if (s->pointer == 12) then s->pointer = 0
397       *   - else: s->pointer += 1
398       *
399       * Reading an invalid address return 0.
400       */
401      if (s->pointer == LSM303DLHC_MAG_REG_OUT_Y_L) {
402          s->pointer = LSM303DLHC_MAG_REG_OUT_X_H;
403      } else if (s->pointer == LSM303DLHC_MAG_REG_IRC) {
404          s->pointer = LSM303DLHC_MAG_REG_CRA;
405      } else {
406          s->pointer++;
407      }
408  
409      return resp;
410  }
411  
412  /*
413   * Bus state change handler.
414   */
lsm303dlhc_mag_event(I2CSlave * i2c,enum i2c_event event)415  static int lsm303dlhc_mag_event(I2CSlave *i2c, enum i2c_event event)
416  {
417      LSM303DLHCMagState *s = LSM303DLHC_MAG(i2c);
418  
419      switch (event) {
420      case I2C_START_SEND:
421          break;
422      case I2C_START_RECV:
423          lsm303dlhc_mag_read(s);
424          break;
425      case I2C_FINISH:
426          lsm303dlhc_mag_finish(s);
427          break;
428      case I2C_NACK:
429          break;
430      default:
431          return -1;
432      }
433  
434      s->len = 0;
435      return 0;
436  }
437  
438  /*
439   * Device data description using VMSTATE macros.
440   */
441  static const VMStateDescription vmstate_lsm303dlhc_mag = {
442      .name = "LSM303DLHC_MAG",
443      .version_id = 0,
444      .minimum_version_id = 0,
445      .fields = (const VMStateField[]) {
446  
447          VMSTATE_I2C_SLAVE(parent_obj, LSM303DLHCMagState),
448          VMSTATE_UINT8(len, LSM303DLHCMagState),
449          VMSTATE_UINT8(buf, LSM303DLHCMagState),
450          VMSTATE_UINT8(pointer, LSM303DLHCMagState),
451          VMSTATE_UINT8(cra, LSM303DLHCMagState),
452          VMSTATE_UINT8(crb, LSM303DLHCMagState),
453          VMSTATE_UINT8(mr, LSM303DLHCMagState),
454          VMSTATE_INT16(x, LSM303DLHCMagState),
455          VMSTATE_INT16(z, LSM303DLHCMagState),
456          VMSTATE_INT16(y, LSM303DLHCMagState),
457          VMSTATE_INT16(x_lock, LSM303DLHCMagState),
458          VMSTATE_INT16(z_lock, LSM303DLHCMagState),
459          VMSTATE_INT16(y_lock, LSM303DLHCMagState),
460          VMSTATE_UINT8(sr, LSM303DLHCMagState),
461          VMSTATE_UINT8(ira, LSM303DLHCMagState),
462          VMSTATE_UINT8(irb, LSM303DLHCMagState),
463          VMSTATE_UINT8(irc, LSM303DLHCMagState),
464          VMSTATE_INT16(temperature, LSM303DLHCMagState),
465          VMSTATE_INT16(temperature_lock, LSM303DLHCMagState),
466          VMSTATE_END_OF_LIST()
467      }
468  };
469  
470  /*
471   * Put the device into post-reset default state.
472   */
lsm303dlhc_mag_default_cfg(LSM303DLHCMagState * s)473  static void lsm303dlhc_mag_default_cfg(LSM303DLHCMagState *s)
474  {
475      /* Set the device into is default reset state. */
476      s->len = 0;
477      s->pointer = 0;         /* Current register. */
478      s->buf = 0;             /* Shared buffer. */
479      s->cra = 0x10;          /* Temp Enabled = 0, Data Rate = 15.0 Hz. */
480      s->crb = 0x20;          /* Gain = +/- 1.3 Gauss. */
481      s->mr = 0x3;            /* Operating Mode = Sleep. */
482      s->x = 0;
483      s->z = 0;
484      s->y = 0;
485      s->x_lock = 0;
486      s->z_lock = 0;
487      s->y_lock = 0;
488      s->sr = 0x1;            /* DRDY = 1. */
489      s->ira = 0x48;
490      s->irb = 0x34;
491      s->irc = 0x33;
492      s->temperature = 0;     /* Default to 0 degrees C (0/8 lsb = 0 C). */
493      s->temperature_lock = 0;
494  }
495  
496  /*
497   * Callback handler when DeviceState 'reset' is set to true.
498   */
lsm303dlhc_mag_reset(DeviceState * dev)499  static void lsm303dlhc_mag_reset(DeviceState *dev)
500  {
501      I2CSlave *i2c = I2C_SLAVE(dev);
502      LSM303DLHCMagState *s = LSM303DLHC_MAG(i2c);
503  
504      /* Set the device into its default reset state. */
505      lsm303dlhc_mag_default_cfg(s);
506  }
507  
508  /*
509   * Initialisation of any public properties.
510   */
lsm303dlhc_mag_initfn(Object * obj)511  static void lsm303dlhc_mag_initfn(Object *obj)
512  {
513      object_property_add(obj, "mag-x", "int",
514                  lsm303dlhc_mag_get_x,
515                  lsm303dlhc_mag_set_x, NULL, NULL);
516  
517      object_property_add(obj, "mag-y", "int",
518                  lsm303dlhc_mag_get_y,
519                  lsm303dlhc_mag_set_y, NULL, NULL);
520  
521      object_property_add(obj, "mag-z", "int",
522                  lsm303dlhc_mag_get_z,
523                  lsm303dlhc_mag_set_z, NULL, NULL);
524  
525      object_property_add(obj, "temperature", "int",
526                  lsm303dlhc_mag_get_temperature,
527                  lsm303dlhc_mag_set_temperature, NULL, NULL);
528  }
529  
530  /*
531   * Set the virtual method pointers (bus state change, tx/rx, etc.).
532   */
lsm303dlhc_mag_class_init(ObjectClass * klass,void * data)533  static void lsm303dlhc_mag_class_init(ObjectClass *klass, void *data)
534  {
535      DeviceClass *dc = DEVICE_CLASS(klass);
536      I2CSlaveClass *k = I2C_SLAVE_CLASS(klass);
537  
538      device_class_set_legacy_reset(dc, lsm303dlhc_mag_reset);
539      dc->vmsd = &vmstate_lsm303dlhc_mag;
540      k->event = lsm303dlhc_mag_event;
541      k->recv = lsm303dlhc_mag_recv;
542      k->send = lsm303dlhc_mag_send;
543  }
544  
545  static const TypeInfo lsm303dlhc_mag_info = {
546      .name = TYPE_LSM303DLHC_MAG,
547      .parent = TYPE_I2C_SLAVE,
548      .instance_size = sizeof(LSM303DLHCMagState),
549      .instance_init = lsm303dlhc_mag_initfn,
550      .class_init = lsm303dlhc_mag_class_init,
551  };
552  
lsm303dlhc_mag_register_types(void)553  static void lsm303dlhc_mag_register_types(void)
554  {
555      type_register_static(&lsm303dlhc_mag_info);
556  }
557  
558  type_init(lsm303dlhc_mag_register_types)
559