include/media/v4l2-cci.h

   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
  14 struct i2c_client;
  15 struct 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  */
  25 struct 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  */
  69 int 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  */
  82 int 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  */
 100 int 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  */
 122 int 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  */
 137 struct regmap *devm_cci_regmap_init_i2c(struct i2c_client *client,
 138                                         int reg_addr_bits);
 139 #endif
 140
 141 #endif