zephyr: emul: Add common code for I2C emulators

Emulators of I2C devices have similar handling of I2C messages, locking
mechanism for multithread code, custom user functions and user triggered
failing on specific register. These functionalities are exported to
common code which will replace current functions in emulators of I2C
devices.

BUG=none
BRANCH=none
TEST=none

Signed-off-by: Tomasz Michalec <tm@semihalf.com>
Change-Id: Ib2c1a6596127dad1250d0051a312a837fc03ce20
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3140201
Commit-Queue: Jeremy Bettis <jbettis@chromium.org>
Reviewed-by: Jeremy Bettis <jbettis@chromium.org>

4 files changed, 807 insertions, 0 deletions

diff --git a/zephyr/emul/CMakeLists.txt b/zephyr/emul/CMakeLists.txt
index bd1d749267..f1e38ee078 100644
--- a/zephyr/emul/CMakeLists.txt
+++ b/zephyr/emul/CMakeLists.txt
@@ -2,6 +2,7 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+zephyr_library_sources_ifdef(CONFIG_EMUL_COMMON_I2C	emul_common_i2c.c)
 zephyr_library_sources_ifdef(CONFIG_EMUL_SMART_BATTERY	emul_smart_battery.c)
 zephyr_library_sources_ifdef(CONFIG_EMUL_BMA255		emul_bma255.c)
 zephyr_library_sources_ifdef(CONFIG_EMUL_BC12_DETECT_PI3USB9201	emul_pi3usb9201.c)
diff --git a/zephyr/emul/Kconfig b/zephyr/emul/Kconfig
index 346d419862..4557117985 100644
--- a/zephyr/emul/Kconfig
+++ b/zephyr/emul/Kconfig
@@ -2,6 +2,13 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+config EMUL_COMMON_I2C
+	bool "Common handler for I2C emulator messages"
+	help
+	  Enable common code that is used by many emulators of devices on I2C
+	  bus. It allows to share code for handling I2C messages, locking and
+	  custom user handlers between these emulators.
+
 config EMUL_SMART_BATTERY
 	bool "Smart Battery emulator"
 	help
diff --git a/zephyr/emul/emul_common_i2c.c b/zephyr/emul/emul_common_i2c.c
new file mode 100644
index 0000000000..6cd93dfe18
--- /dev/null
+++ b/zephyr/emul/emul_common_i2c.c
@@ -0,0 +1,432 @@
+/* Copyright 2021 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#define LOG_LEVEL CONFIG_I2C_LOG_LEVEL
+#include <logging/log.h>
+LOG_MODULE_REGISTER(emul_common_i2c);
+
+#include <device.h>
+#include <emul.h>
+#include <drivers/i2c.h>
+#include <drivers/i2c_emul.h>
+
+#include "emul/emul_common_i2c.h"
+
+/** Check description in emul_common_i2c.h */
+int i2c_common_emul_lock_data(struct i2c_emul *emul, k_timeout_t timeout)
+{
+	struct i2c_common_emul_data *data;
+
+	data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+
+	return k_mutex_lock(&data->data_mtx, timeout);
+}
+
+/** Check description in emul_common_i2c.h */
+int i2c_common_emul_unlock_data(struct i2c_emul *emul)
+{
+	struct i2c_common_emul_data *data;
+
+	data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+
+	return k_mutex_unlock(&data->data_mtx);
+}
+
+/** Check description in emul_common_i2c.h */
+void i2c_common_emul_set_write_func(struct i2c_emul *emul,
+				    i2c_common_emul_write_func func, void *data)
+{
+	struct i2c_common_emul_data *emul_data;
+
+	emul_data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+	emul_data->write_func = func;
+	emul_data->write_func_data = data;
+}
+
+/** Check description in emul_common_i2c.h */
+void i2c_common_emul_set_read_func(struct i2c_emul *emul,
+				   i2c_common_emul_read_func func, void *data)
+{
+	struct i2c_common_emul_data *emul_data;
+
+	emul_data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+	emul_data->read_func = func;
+	emul_data->read_func_data = data;
+}
+
+/** Check description in emul_common_i2c.h */
+void i2c_common_emul_set_read_fail_reg(struct i2c_emul *emul, int reg)
+{
+	struct i2c_common_emul_data *data;
+
+	data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+	data->read_fail_reg = reg;
+}
+
+/** Check description in emul_common_i2c.h */
+void i2c_common_emul_set_write_fail_reg(struct i2c_emul *emul, int reg)
+{
+	struct i2c_common_emul_data *data;
+
+	data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+	data->write_fail_reg = reg;
+}
+
+/**
+ * @brief Call start_write emulator callback if set. It handles first byte
+ *        of I2C write message.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ *
+ * @retval start_write emulator callback return code
+ */
+static int i2c_common_emul_start_write(struct i2c_emul *emul,
+				       struct i2c_common_emul_data *data)
+{
+	int ret = 0;
+
+	data->msg_byte = 0;
+
+	if (data->start_write) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->start_write(emul, data->cur_reg);
+		k_mutex_unlock(&data->data_mtx);
+	}
+
+	return ret;
+}
+
+/**
+ * @brief Call finish_write emulator callback if set. It is called after last
+ *        byte of I2C write message.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ *
+ * @retval finish_write emulator callback return code
+ */
+static int i2c_common_emul_finish_write(struct i2c_emul *emul,
+					struct i2c_common_emul_data *data)
+{
+	int ret = 0;
+
+	if (data->finish_write) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->finish_write(emul, data->cur_reg, data->msg_byte);
+		k_mutex_unlock(&data->data_mtx);
+	}
+
+	return ret;
+}
+
+/**
+ * @brief Call start_read emulator callback if set. It prepares emulator at
+ *        the beginning of I2C read message.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ *
+ * @retval start_read emulator callback return code
+ */
+static int i2c_common_emul_start_read(struct i2c_emul *emul,
+				      struct i2c_common_emul_data *data)
+{
+	int ret = 0;
+
+	data->msg_byte = 0;
+
+	if (data->start_read) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->start_read(emul, data->cur_reg);
+		k_mutex_unlock(&data->data_mtx);
+	}
+
+	return ret;
+}
+
+/**
+ * @brief Call finish_read emulator callback if set. It is called after last
+ *        byte of I2C read message.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ *
+ * @retval finish_read emulator callback return code
+ */
+static int i2c_common_emul_finish_read(struct i2c_emul *emul,
+				       struct i2c_common_emul_data *data)
+{
+	int ret = 0;
+
+	if (data->finish_read) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->finish_read(emul, data->cur_reg, data->msg_byte);
+		k_mutex_unlock(&data->data_mtx);
+	}
+
+	return ret;
+}
+
+/**
+ * @brief Handle byte from I2C write message. First custom user handler is
+ *        called (if set). Next accessed register is compared with selected
+ *        by user fail register. Lastly, specific I2C device emulator handler
+ *        is called.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ * @param val Value of current byte
+ *
+ * @retval 0 If successful
+ * @retval -EIO General input / output error
+ */
+static int i2c_common_emul_write_byte(struct i2c_emul *emul,
+				      struct i2c_common_emul_data *data,
+				      uint8_t val)
+{
+	int reg, ret;
+
+	/* Custom user handler */
+	if (data->write_func) {
+		ret = data->write_func(emul, data->cur_reg, val, data->msg_byte,
+				       data->write_func_data);
+		if (ret < 0) {
+			return -EIO;
+		} else if (ret == 0) {
+			return 0;
+		}
+	}
+	/* Check if user wants to fail on accessed register */
+	if (data->access_reg) {
+		reg = data->access_reg(emul, data->cur_reg, data->msg_byte,
+				       false /* = read */);
+	} else {
+		/* Ignore first (register address) byte */
+		reg = data->cur_reg + data->msg_byte - 1;
+	}
+
+	if (data->write_fail_reg == reg ||
+	    data->write_fail_reg == I2C_COMMON_EMUL_FAIL_ALL_REG) {
+		return -EIO;
+	}
+	/* Emulator handler */
+	if (data->write_byte) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->write_byte(emul, data->cur_reg, val,
+				       data->msg_byte);
+		k_mutex_unlock(&data->data_mtx);
+		if (ret) {
+			return -EIO;
+		}
+	}
+
+	return 0;
+}
+
+/**
+ * @brief Handle byte from I2C read message. First custom user handler is
+ *        called (if set). Next accessed register is compared with selected
+ *        by user fail register. Lastly, specific I2C device emulator handler
+ *        is called.
+ *
+ * @param emul Pointer to emulator
+ * @param data Pointer to emulator data
+ * @param val Pointer to buffer where current response byte should be stored
+ *
+ * @retval 0 If successful
+ * @retval -EIO General input / output error
+ */
+static int i2c_common_emul_read_byte(struct i2c_emul *emul,
+				     struct i2c_common_emul_data *data,
+				     uint8_t *val)
+{
+	int reg, ret;
+
+	/* Custom user handler */
+	if (data->read_func) {
+		ret = data->read_func(emul, data->cur_reg, val, data->msg_byte,
+				      data->read_func_data);
+		if (ret < 0) {
+			return -EIO;
+		} else if (ret == 0) {
+			return 0;
+		}
+	}
+	/* Check if user wants to fail on accessed register */
+	if (data->access_reg) {
+		reg = data->access_reg(emul, data->cur_reg, data->msg_byte,
+				       true /* = read */);
+	} else {
+		reg = data->cur_reg + data->msg_byte;
+	}
+
+	if (data->read_fail_reg == reg ||
+	    data->read_fail_reg == I2C_COMMON_EMUL_FAIL_ALL_REG) {
+		return -EIO;
+	}
+	/* Emulator handler */
+	if (data->read_byte) {
+		k_mutex_lock(&data->data_mtx, K_FOREVER);
+		ret = data->read_byte(emul, data->cur_reg, val, data->msg_byte);
+		k_mutex_unlock(&data->data_mtx);
+		if (ret) {
+			return -EIO;
+		}
+	}
+
+	return 0;
+}
+
+/** Check description in emul_common_i2c.h */
+int i2c_common_emul_transfer(struct i2c_emul *emul, struct i2c_msg *msgs,
+			     int num_msgs, int addr)
+{
+	const struct i2c_common_emul_cfg *cfg;
+	struct i2c_common_emul_data *data;
+	bool read, stop;
+	int ret, i;
+
+	data = CONTAINER_OF(emul, struct i2c_common_emul_data, emul);
+	cfg = data->cfg;
+
+	if (cfg->addr != addr) {
+		LOG_ERR("Address mismatch, expected %02x, got %02x", cfg->addr,
+			addr);
+		return -EIO;
+	}
+
+	i2c_dump_msgs("emul", msgs, num_msgs, addr);
+
+	for (; num_msgs > 0; num_msgs--, msgs++) {
+		read = msgs->flags & I2C_MSG_READ;
+		stop = msgs->flags & I2C_MSG_STOP;
+
+		switch (data->msg_state) {
+		case I2C_COMMON_EMUL_IN_WRITE:
+			if (read) {
+				data->msg_state = I2C_COMMON_EMUL_NONE_MSG;
+				ret = i2c_common_emul_finish_write(emul, data);
+				if (ret) {
+					return ret;
+				}
+				ret = i2c_common_emul_start_read(emul, data);
+				if (ret) {
+					return ret;
+				}
+			}
+			break;
+		case I2C_COMMON_EMUL_IN_READ:
+			if (!read) {
+				data->msg_state = I2C_COMMON_EMUL_NONE_MSG;
+				ret = i2c_common_emul_finish_read(emul, data);
+				if (ret) {
+					return ret;
+				}
+				/* Wait for write message with acctual data */
+				if (msgs->len == 0) {
+					continue;
+				}
+				/* Dispatch command/register address */
+				data->cur_reg = msgs->buf[0];
+				ret = i2c_common_emul_start_write(emul, data);
+				if (ret) {
+					return ret;
+				}
+			}
+			break;
+		case I2C_COMMON_EMUL_NONE_MSG:
+			if (read) {
+				ret = i2c_common_emul_start_read(emul, data);
+				if (ret) {
+					return ret;
+				}
+			} else {
+				/* Wait for write message with acctual data */
+				if (msgs->len == 0) {
+					continue;
+				}
+				/* Dispatch command/register address */
+				data->cur_reg = msgs->buf[0];
+				ret = i2c_common_emul_start_write(emul, data);
+				if (ret) {
+					return ret;
+				}
+			}
+		}
+
+		data->msg_state = read ? I2C_COMMON_EMUL_IN_READ
+				       : I2C_COMMON_EMUL_IN_WRITE;
+
+		if (stop) {
+			data->msg_state = I2C_COMMON_EMUL_NONE_MSG;
+		}
+
+		if (!read) {
+			/*
+			 * All current emulators use first byte of write message
+			 * as command/register address for following write bytes
+			 * or read message. Skip first byte which was dispatched
+			 * already.
+			 */
+			if (data->msg_byte == 0) {
+				data->msg_byte = 1;
+				i = 1;
+			} else {
+				i = 0;
+			}
+			/* Dispatch wrtie command */
+			for (; i < msgs->len; i++, data->msg_byte++) {
+				ret = i2c_common_emul_write_byte(emul, data,
+								 msgs->buf[i]);
+				if (ret) {
+					return ret;
+				}
+			}
+			/* Finish write command */
+			if (stop) {
+				ret = i2c_common_emul_finish_write(emul, data);
+				if (ret) {
+					return ret;
+				}
+			}
+		} else {
+			/* Dispatch read command */
+			for (i = 0; i < msgs->len; i++, data->msg_byte++) {
+				ret = i2c_common_emul_read_byte(emul, data,
+							       &(msgs->buf[i]));
+				if (ret) {
+					return ret;
+				}
+			}
+
+			/* Finish read command */
+			if (stop) {
+				ret = i2c_common_emul_finish_read(emul, data);
+				if (ret) {
+					return ret;
+				}
+			}
+		}
+	}
+
+	return 0;
+}
+
+/** Check description in emul_common_i2c.h */
+void i2c_common_emul_init(struct i2c_common_emul_data *data)
+{
+	data->msg_state = I2C_COMMON_EMUL_NONE_MSG;
+	data->msg_byte = 0;
+	data->cur_reg = 0;
+
+	data->write_func = NULL;
+	data->read_func = NULL;
+
+	data->write_fail_reg = I2C_COMMON_EMUL_NO_FAIL_REG;
+	data->read_fail_reg = I2C_COMMON_EMUL_NO_FAIL_REG;
+
+	k_mutex_init(&data->data_mtx);
+}
diff --git a/zephyr/include/emul/emul_common_i2c.h b/zephyr/include/emul/emul_common_i2c.h
new file mode 100644
index 0000000000..3f48e2b33a
--- /dev/null
+++ b/zephyr/include/emul/emul_common_i2c.h
@@ -0,0 +1,367 @@
+/* Copyright 2021 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ *
+ * @brief Common code used by devices emulated on I2C bus
+ */
+
+#ifndef __EMUL_COMMON_I2C_H
+#define __EMUL_COMMON_I2C_H
+
+#include <emul.h>
+#include <drivers/i2c.h>
+#include <drivers/i2c_emul.h>
+
+/**
+ * @brief Common I2C API useb by emulators
+ * @defgroup i2c_common_emul common I2C emulator's code
+ * @{
+ *
+ * I2C common emulator functionality is dispatching I2C messages. It supports
+ * setting custom user handler and selecting register on which access emulator
+ * should fail. To use common I2C handling, emulator should call or setup
+ * @ref i2c_common_emul_transfer as transfer callback of i2c_emul_api and
+ * register emulator with @ref i2c_common_emul_data structure as data. In data
+ * structure, emualtor should set callback called before read/write I2C message
+ * (start_read, start_write), for each byte of I2C message (read_byte,
+ * write_byte) and after I2C message (finish_read, finish_byte). If specific
+ * function is not needed by emulator, than it can be set to NULL.
+ *
+ * @ref i2c_common_emul_lock_data and @ref i2c_common_emul_unlock_data functions
+ * may be used to guard emulator data when accessed from multiple threads.
+ *
+ * User of emulator with common I2C code can use following API to define custom
+ * behaviour of emulator:
+ *
+ * - call @ref i2c_common_emul_set_read_func and
+ *   @ref i2c_common_emul_set_write_func to setup custom handlers for I2C
+ *   messages
+ * - call @ref i2c_common_emul_set_read_fail_reg and
+ *   @ref i2c_common_emul_set_write_fail_reg to configure emulator to fail on
+ *   given register read or write
+ */
+
+/**
+ * Special register values used in @ref i2c_common_emul_set_read_fail_reg and
+ * @ref i2c_common_emul_set_write_fail_reg
+ */
+#define I2C_COMMON_EMUL_FAIL_ALL_REG	(-1)
+#define I2C_COMMON_EMUL_NO_FAIL_REG	(-2)
+
+/**
+ * Describe if there is no ongoing I2C message or if there is message handled
+ * at the moment (last message doesn't ended with stop or write is not followed
+ * by read).
+ */
+enum i2c_common_emul_msg_state {
+	I2C_COMMON_EMUL_NONE_MSG,
+	I2C_COMMON_EMUL_IN_WRITE,
+	I2C_COMMON_EMUL_IN_READ
+};
+
+/**
+ * @brief Function type that is used by I2C device emulator for first byte of
+ *        I2C write message.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by write command (first byte of I2C
+ *            write message)
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_start_write_func)(struct i2c_emul *emul, int reg);
+
+/**
+ * @brief Function type that is used by I2C device emulator at the end of
+ *        I2C write message.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by write command (first byte of I2C
+ *            write message)
+ * @param bytes Number of bytes received from the I2C write message
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_finish_write_func)(struct i2c_emul *emul, int reg,
+						 int bytes);
+
+/**
+ * @brief Function type that is used by I2C device emulator on each byte of
+ *        I2C write message (except first byte).
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by write command (first byte of I2C
+ *            write message)
+ * @param val Value of current byte
+ * @param bytes Number of bytes already received from the I2C write message
+ *              (excluding current byte)
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_write_byte_func)(struct i2c_emul *emul, int reg,
+					       uint8_t val, int bytes);
+
+/**
+ * @brief Function type that is used by I2C device emulator before first byte of
+ *        I2C read message.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by read command (first byte of last
+ *            I2C write message)
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_start_read_func)(struct i2c_emul *emul, int reg);
+
+/**
+ * @brief Function type that is used by I2C device emulator at the end of
+ *        I2C read message.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by read command (first byte of last
+ *            I2C write message)
+ * @param bytes Number of bytes responeded to the I2C read message
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_finish_read_func)(struct i2c_emul *emul, int reg,
+						int bytes);
+
+/**
+ * @brief Function type that is used by I2C device emulator on each byte of
+ *        I2C read message.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by read command (first byte of last
+ *            I2C write message)
+ * @param val Pointer to buffer where current response byte should be stored
+ * @param bytes Number of bytes already responded to the I2C read message
+ *              (excluding current byte)
+ *
+ * @return 0 on success
+ * @return -EIO on error
+ */
+typedef int (*i2c_common_emul_read_byte_func)(struct i2c_emul *emul, int reg,
+					      uint8_t *val, int bytes);
+
+/**
+ * @brief Function type that is used by I2C device emulator to select register
+ *        address that should be compared with fail register set by user using
+ *        @ref i2c_common_emul_set_read_fail_reg and
+ *        @ref i2c_common_emul_set_write_fail_reg
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by read/write command (first byte
+ *            of last I2C write message)
+ * @param bytes Number of bytes already processed in the I2C message handler
+ *              (excluding current byte)
+ * @param read If current I2C message is read
+ *
+ * @return Register address that should be compared with user-defined fail
+ *         register
+ */
+typedef int (*i2c_common_emul_access_reg_func)(struct i2c_emul *emul, int reg,
+					       int bytes, bool read);
+
+/**
+ * @brief Custom function type that is used as user-defined callback in read
+ *        I2C messages handling.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by read command (first byte of last
+ *            I2C write message)
+ * @param val Pointer to buffer where current response byte should be stored
+ * @param bytes Number of bytes already responded to the I2C read message
+ *              (excluding current byte)
+ * @param data Pointer to custom user data
+ *
+ * @return 0 on success
+ * @return 1 continue with normal emulator handler
+ * @return negative on error
+ */
+typedef int (*i2c_common_emul_read_func)(struct i2c_emul *emul, int reg,
+					 uint8_t *val, int bytes, void *data);
+
+/**
+ * @brief Custom function type that is used as user-defined callback in write
+ *        I2C messages handling.
+ *
+ * @param emul Pointer to emulator
+ * @param reg Address which is now accessed by write command (first byte of I2C
+ *            write message)
+ * @param val Value of current byte
+ * @param bytes Number of bytes already received from the I2C write message
+ *              (excluding current byte)
+ * @param data Pointer to custom user data
+ *
+ * @return 0 on success
+ * @return 1 continue with normal emulator handler
+ * @return negative on error
+ */
+typedef int (*i2c_common_emul_write_func)(struct i2c_emul *emul, int reg,
+					  uint8_t val, int bytes, void *data);
+
+/** Static configuration, common for all i2c emulators */
+struct i2c_common_emul_cfg {
+	/** Label of the I2C bus this emulator connects to */
+	const char *i2c_label;
+	/** Pointer to run-time data */
+	struct i2c_common_emul_data *data;
+	/** Address of emulator on i2c bus */
+	uint16_t addr;
+};
+
+/** Run-time data used by the emulator, common for all i2c emulators */
+struct i2c_common_emul_data {
+	/** I2C emulator detail */
+	struct i2c_emul emul;
+	/** Emulator device */
+	const struct device *i2c;
+	/** Configuration information */
+	const struct i2c_common_emul_cfg *cfg;
+
+	/** Current state of I2C bus (if emulator is handling message) */
+	enum i2c_common_emul_msg_state msg_state;
+	/** Number of already handled bytes in ongoing message */
+	int msg_byte;
+	/** Register selected in last write command */
+	uint8_t cur_reg;
+
+	/** Custom write function called on I2C write opperation */
+	i2c_common_emul_write_func write_func;
+	/** Data passed to custom write function */
+	void *write_func_data;
+	/** Custom read function called on I2C read opperation */
+	i2c_common_emul_read_func read_func;
+	/** Data passed to custom read function */
+	void *read_func_data;
+
+	/** Control if read should fail on given register */
+	int read_fail_reg;
+	/** Control if write should fail on given register */
+	int write_fail_reg;
+
+	/** Emulator function, called for first byte of write message */
+	i2c_common_emul_start_write_func start_write;
+	/** Emulator function, called for each byte of write message */
+	i2c_common_emul_write_byte_func write_byte;
+	/** Emulator function, called at the end of write message */
+	i2c_common_emul_finish_write_func finish_write;
+
+	/** Emulator function, called before first byte of read message */
+	i2c_common_emul_start_read_func start_read;
+	/** Emulator function, called for each byte of read message */
+	i2c_common_emul_read_byte_func read_byte;
+	/** Emulator function, called at the end of read message */
+	i2c_common_emul_finish_read_func finish_read;
+
+	/**
+	 * Emulator function, called to get register that should be checked
+	 * if was selected by user in set_read/write_fail_reg.
+	 */
+	i2c_common_emul_access_reg_func access_reg;
+
+	/** Mutex used to control access to emulator data */
+	struct k_mutex data_mtx;
+};
+
+/**
+ * @brief Lock access to emulator properties. After acquiring lock, user
+ *        may change emulator behaviour in multi-thread setup.
+ *
+ * @param emul Pointer to emulator
+ * @param timeout Timeout in getting lock
+ *
+ * @return k_mutex_lock return code
+ */
+int i2c_common_emul_lock_data(struct i2c_emul *emul, k_timeout_t timeout);
+
+/**
+ * @brief Unlock access to emulator properties.
+ *
+ * @param emul Pointer to emulator
+ *
+ * @return k_mutex_unlock return code
+ */
+int i2c_common_emul_unlock_data(struct i2c_emul *emul);
+
+/**
+ * @brief Set write handler for I2C messages. This function is called before
+ *        generic handler.
+ *
+ * @param emul Pointer to emulator
+ * @param func Pointer to custom function
+ * @param data User data passed on call of custom function
+ */
+void i2c_common_emul_set_write_func(struct i2c_emul *emul,
+				    i2c_common_emul_write_func func,
+				    void *data);
+
+/**
+ * @brief Set read handler for I2C messages. This function is called before
+ *        generic handler.
+ *
+ * @param emul Pointer to emulator
+ * @param func Pointer to custom function
+ * @param data User data passed on call of custom function
+ */
+void i2c_common_emul_set_read_func(struct i2c_emul *emul,
+				   i2c_common_emul_read_func func, void *data);
+
+/**
+ * @brief Setup fail on read of given register of emulator
+ *
+ * @param emul Pointer to emulator
+ * @param reg Register address or one of special values
+ *            (I2C_COMMON_EMUL_FAIL_ALL_REG, I2C_COMMON_EMUL_NO_FAIL_REG)
+ */
+void i2c_common_emul_set_read_fail_reg(struct i2c_emul *emul, int reg);
+
+/**
+ * @brief Setup fail on write of given register of emulator
+ *
+ * @param emul Pointer to emulator
+ * @param reg Register address or one of special values
+ *            (I2C_COMMON_EMUL_FAIL_ALL_REG, I2C_COMMON_EMUL_NO_FAIL_REG)
+ */
+void i2c_common_emul_set_write_fail_reg(struct i2c_emul *emul, int reg);
+
+/**
+ * @biref Emulate an I2C transfer to an emulator
+ *
+ * This is common function used by I2C device emulators. It handles dispatching
+ * I2C message, calling user custom functions, failing on reading/writing
+ * registers selected by user and calling device specific functions.
+ *
+ * @param emul I2C emulation information
+ * @param msgs List of messages to process
+ * @param num_msgs Number of messages to process
+ * @param addr Address of the I2C target device
+ *
+ * @retval 0 If successful
+ * @retval -EIO General input / output error
+ */
+int i2c_common_emul_transfer(struct i2c_emul *emul, struct i2c_msg *msgs,
+			     int num_msgs, int addr);
+
+/**
+ * @brief Initialize common emulator data structure
+ *
+ * @param data Pointer to emulator data
+ */
+void i2c_common_emul_init(struct i2c_common_emul_data *data);
+
+/**
+ * @}
+ */
+
+#endif /* __EMUL_COMMON_I2C_H */