Zephyr in tree driver use

This page holding notes on how to use Zephyr in-tree drivers. This page was started in 2021, but we're adding to it 2022 November as we revisit and refactor a Zephyr driver for Kionix KX132 sensor.

Code excerpt: IIS2DH driver routine to query sensor for its WHOAMI value

+
+2021-10-13
+
+In file ./z4-sandbox-kionix-work/modules/hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.c
+
+ 789 /**
+ 790   * @defgroup  IIS2DH_Common
+ 791   * @brief     This section group common usefull functions
+ 792   * @{
+ 793   *
+ 794   */
+ 795 
+ 796 /**
+ 797   * @brief  DeviceWhoamI .[get]
+ 798   *
+ 799   * @param  ctx      read / write interface definitions
+ 800   * @param  buff     buffer that stores data read
+ 801   * @retval          interface status (MANDATORY: return 0 -> no Error)
+ 802   *
+ 803   */
+ 804 int32_t iis2dh_device_id_get(stmdev_ctx_t *ctx, uint8_t *buff)
+ 805 {
+ 806   int32_t ret;
+ 807   ret = iis2dh_read_reg(ctx, IIS2DH_WHO_AM_I, buff, 1);
+ 808   return ret;
+ 809 }
+ 810 /**
+ 811   * @brief  Self Test.[set]
+ 812   *
+ 813   * @param  ctx      read / write interface definitions
+ 814   * @param  val      change the values of st in reg CTRL_REG4
+ 815   * @retval          interface status (MANDATORY: return 0 -> no Error)
+ 816   *
+ 817   */
+

(2) Function prototype and opening line for IIS2DH "read WHOAMI value" function:

ted@localhost:~/projects/zephyr-based/z4-sandbox-kionix-work/modules$ grep -nr iis2dh_device_id_get ./*
./hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.h:762:int32_t iis2dh_device_id_get(stmdev_ctx_t *ctx, uint8_t *buff);
./hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.c:804:int32_t iis2dh_device_id_get(stmdev_ctx_t *ctx, uint8_t *buff)
ted@localhost:~/projects/zephyr-based/z4-sandbox-kionix-work/modules$

(3) Ok now a year ahead of our first posting of this code excerpt, we can understand a little better what an `stmdev_ctx_t` data structure provides. An "STMicro device context type" provides driver code function pointers to generalized register_read and register_write functions. The function pointers allow for a use of Zephyr device tree macros, to conditionally select between compilation of I2C interfacing register functions and SPI interfacing register functions. This is where the driver design provides a build time flexibility, in Zephyr RTOS context, to support both I2C and SPI. For a given sensor instance one or the other is selected. See [1] for the conditional macros which check for valid I2C and SPI bus controller instances.

zephyr/../modules/hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.h:119:} stmdev_ctx_t;

102 /** @addtogroup  Interfaces_Functions
103   * @brief       This section provide a set of functions used to read and
104   *              write a generic register of the device.
105   *              MANDATORY: return 0 -> no Error.
106   * @{
107   *
108   */
109 
110 typedef int32_t (*stmdev_write_ptr)(void *, uint8_t, uint8_t*, uint16_t);
111 typedef int32_t (*stmdev_read_ptr) (void *, uint8_t, uint8_t*, uint16_t);
112 
113 typedef struct {
114   /** Component mandatory fields **/
115   stmdev_write_ptr  write_reg;
116   stmdev_read_ptr   read_reg;
117   /** Customizable optional pointer **/
118   void *handle;
119 } stmdev_ctx_t;

(4) Need to understand how to initialize and use the STMicro IIS2DH driver data structure named `stmdev_ctx_t`:

./drivers/sensor/iis2dh/iis2dh_i2c.c:39:stmdev_ctx_t iis2dh_i2c_ctx = {
 40         .read_reg = (stmdev_read_ptr) iis2dh_i2c_read,
 41         .write_reg = (stmdev_write_ptr) iis2dh_i2c_write,
 42 };

. . . The search to find this assignment is:

  $ ted@localhost:~/projects/zephyr-based/z4-sandbox-kionix-work/zephyr$ grep -nr stmdev_ctx_t ./*