1/* SPDX-License-Identifier: GPL-2.0 */
  2/*
  3 * MIPI Camera Control Interface (CCI) register access helpers.
  4 *
  5 * Copyright (C) 2023 Hans de Goede <hansg@kernel.org>
  6 */
  7#ifndef _V4L2_CCI_H
  8#define _V4L2_CCI_H
  9
 10#include <linux/bitfield.h>
 11#include <linux/bits.h>
 12#include <linux/types.h>
 13
 14struct i2c_client;
 15struct regmap;
 16
 17/**
 18 * struct cci_reg_sequence - An individual write from a sequence of CCI writes
 19 *
 20 * @reg: Register address, use CCI_REG#() macros to encode reg width
 21 * @val: Register value
 22 *
 23 * Register/value pairs for sequences of writes.
 24 */
 25struct cci_reg_sequence {
 26	u32 reg;
 27	u64 val;
 28};
 29
 30/*
 31 * Macros to define register address with the register width encoded
 32 * into the higher bits.
 33 */
 34#define CCI_REG_ADDR_MASK		GENMASK(15, 0)
 35#define CCI_REG_WIDTH_SHIFT		16
 36#define CCI_REG_WIDTH_MASK		GENMASK(19, 16)
 37/*
 38 * Private CCI register flags, for the use of drivers.
 39 */
 40#define CCI_REG_PRIVATE_SHIFT		28U
 41#define CCI_REG_PRIVATE_MASK		GENMASK(31U, CCI_REG_PRIVATE_SHIFT)
 42
 43#define CCI_REG_WIDTH_BYTES(x)		FIELD_GET(CCI_REG_WIDTH_MASK, x)
 44#define CCI_REG_WIDTH(x)		(CCI_REG_WIDTH_BYTES(x) << 3)
 45#define CCI_REG_ADDR(x)			FIELD_GET(CCI_REG_ADDR_MASK, x)
 46#define CCI_REG_LE			BIT(20)
 47
 48#define CCI_REG8(x)			((1 << CCI_REG_WIDTH_SHIFT) | (x))
 49#define CCI_REG16(x)			((2 << CCI_REG_WIDTH_SHIFT) | (x))
 50#define CCI_REG24(x)			((3 << CCI_REG_WIDTH_SHIFT) | (x))
 51#define CCI_REG32(x)			((4 << CCI_REG_WIDTH_SHIFT) | (x))
 52#define CCI_REG64(x)			((8 << CCI_REG_WIDTH_SHIFT) | (x))
 53#define CCI_REG16_LE(x)			(CCI_REG_LE | (2U << CCI_REG_WIDTH_SHIFT) | (x))
 54#define CCI_REG24_LE(x)			(CCI_REG_LE | (3U << CCI_REG_WIDTH_SHIFT) | (x))
 55#define CCI_REG32_LE(x)			(CCI_REG_LE | (4U << CCI_REG_WIDTH_SHIFT) | (x))
 56#define CCI_REG64_LE(x)			(CCI_REG_LE | (8U << CCI_REG_WIDTH_SHIFT) | (x))
 57
 58/**
 59 * cci_read() - Read a value from a single CCI register
 60 *
 61 * @map: Register map to read from
 62 * @reg: Register address to read, use CCI_REG#() macros to encode reg width
 63 * @val: Pointer to store read value
 64 * @err: Optional pointer to store errors, if a previous error is set
 65 *       then the read will be skipped
 66 *
 67 * Return: %0 on success or a negative error code on failure.
 68 */
 69int cci_read(struct regmap *map, u32 reg, u64 *val, int *err);
 70
 71/**
 72 * cci_write() - Write a value to a single CCI register
 73 *
 74 * @map: Register map to write to
 75 * @reg: Register address to write, use CCI_REG#() macros to encode reg width
 76 * @val: Value to be written
 77 * @err: Optional pointer to store errors, if a previous error is set
 78 *       then the write will be skipped
 79 *
 80 * Return: %0 on success or a negative error code on failure.
 81 */
 82int cci_write(struct regmap *map, u32 reg, u64 val, int *err);
 83
 84/**
 85 * cci_update_bits() - Perform a read/modify/write cycle on
 86 *                     a single CCI register
 87 *
 88 * @map: Register map to update
 89 * @reg: Register address to update, use CCI_REG#() macros to encode reg width
 90 * @mask: Bitmask to change
 91 * @val: New value for bitmask
 92 * @err: Optional pointer to store errors, if a previous error is set
 93 *       then the update will be skipped
 94 *
 95 * Note this uses read-modify-write to update the bits, atomicity with regards
 96 * to other cci_*() register access functions is NOT guaranteed.
 97 *
 98 * Return: %0 on success or a negative error code on failure.
 99 */
100int cci_update_bits(struct regmap *map, u32 reg, u64 mask, u64 val, int *err);
101
102/**
103 * cci_multi_reg_write() - Write multiple registers to the device
104 *
105 * @map: Register map to write to
106 * @regs: Array of structures containing register-address, -value pairs to be
107 *        written, register-addresses use CCI_REG#() macros to encode reg width
108 * @num_regs: Number of registers to write
109 * @err: Optional pointer to store errors, if a previous error is set
110 *       then the write will be skipped
111 *
112 * Write multiple registers to the device where the set of register, value
113 * pairs are supplied in any order, possibly not all in a single range.
114 *
115 * Use of the CCI_REG#() macros to encode reg width is mandatory.
116 *
117 * For raw lists of register-address, -value pairs with only 8 bit
118 * wide writes regmap_multi_reg_write() can be used instead.
119 *
120 * Return: %0 on success or a negative error code on failure.
121 */
122int cci_multi_reg_write(struct regmap *map, const struct cci_reg_sequence *regs,
123			unsigned int num_regs, int *err);
124
125#if IS_ENABLED(CONFIG_V4L2_CCI_I2C)
126/**
127 * devm_cci_regmap_init_i2c() - Create regmap to use with cci_*() register
128 *                              access functions
129 *
130 * @client: i2c_client to create the regmap for
131 * @reg_addr_bits: register address width to use (8 or 16)
132 *
133 * Note the memory for the created regmap is devm() managed, tied to the client.
134 *
135 * Return: %0 on success or a negative error code on failure.
136 */
137struct regmap *devm_cci_regmap_init_i2c(struct i2c_client *client,
138					int reg_addr_bits);
139#endif
140
141#endif