Difference between revisions of "Zephyr in tree driver use"

From Wiki at Neela Nurseries
Jump to: navigation, search
(Starting local page for instructions on how to use, leverage a Zephyr in-tree driver.)
 
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
This page holding notes on how to use Zephyr in-tree drivers.
+
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 [https://github.com/tedhavelka/zephyr-driver-work-v2 a Zephyr driver for Kionix KX132 sensor].
  
<i>Code excerpt:</i>
+
<i>Code excerpt: IIS2DH driver routine to query sensor for its WHOAMI value</i>
 
<pre>
 
<pre>
 
+
 
+
Line 42: Line 42:
  
  
 +
(2)  Function prototype and opening line for IIS2DH "read WHOAMI value" function:
 +
 +
<pre>
 +
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$
 +
</pre>
 +
 +
 +
(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 [https://github.com/zephyrproject-rtos/zephyr/blob/main/drivers/sensor/iis2dh/iis2dh.h] for the conditional macros which check for valid I2C and SPI bus controller instances.
 +
 +
<pre>
 +
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;
 +
</pre>
 +
 +
 +
(4) Need to understand how to initialize and use the STMicro IIS2DH driver data structure named `stmdev_ctx_t`:
 +
 +
<pre>
 +
./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 };
 +
</pre>
 +
 +
. . . The search to find this assignment is:
 +
 +
  $ ted@localhost:~/projects/zephyr-based/z4-sandbox-kionix-work/zephyr$ grep -nr stmdev_ctx_t ./*
  
 
<!-- comment -->
 
<!-- comment -->

Latest revision as of 23:28, 18 November 2022

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 ./*