/* SPDX-License-Identifier: GPL-2.0-only */
/*
* Copyright (c) 2026 Intel Corporation
*/
#ifndef _ICVS_H
#define _ICVS_H
#include <linux/bits.h>
#include <linux/completion.h>
#include <linux/mutex.h>
#include <linux/workqueue.h>
#include <linux/types.h>
#include <linux/wait.h>
#include <media/media-entity.h>
#include <media/v4l2-ctrls.h>
#include <media/v4l2-subdev.h>
/*
* PCI device IDs for all IPU generations that co-exist with the CVS bridge.
* IPU7 (0x645d) is shared by MTL and LNL; IPU7P5 (0xb05d) is shared by
* ARL and PTL. These are not yet in the shared ipu6-pci-table so they are
* listed here alongside the IPU6 family for probe-time IPU discovery.
*/
struct gpio_desc;
struct i2c_client;
/*
* GPIO resource counts (ACPI enumerated).
*
* 4-GPIO configuration has a wake IRQ and supports asynchronous messaging.
* 2-GPIO configuration has no IRQ, so communication is synchronous only.
*/
#define ICVS_GPIO_ASYNC 4
#define ICVS_GPIO_SYNC 2
/* Firmware response prefix (optional, for protocol revision 2.x or newer) */
#define ICVS_PREFIX_VAL 0xCAFEB0BA
/*
* CSI bridge sub-device definitions
*/
/**
* enum icvs_csi_cmd_id - Low-level CSI bridge command identifiers
*
* These numeric IDs are part of the legacy CSI-side protocol not mapped
* directly to the higher level firmware opcodes in enum icvs_command. Only
* a minimal subset is presently issued/handled by the driver. Others are
* reserved for future expansion of the CSI bridge feature set.
*
* @ICVS_CSI_SET_OWNER: Set CSI sensor ownership between host and CVS
* @ICVS_CSI_SET_CONF: Apply CSI link configuration parameters
* @ICVS_CSI_PRIVACY_NOTIF: Notify host of a privacy state transition
*/
enum icvs_csi_cmd_id {
ICVS_CSI_SET_OWNER = 0,
ICVS_CSI_SET_CONF = 2,
ICVS_CSI_PRIVACY_NOTIF = 6,
};
/**
* enum icvs_csi_link_owner - CSI-2 link / sensor ownership
*
* Ownership reflects which endpoint currently controls the attached image
* sensor over the CSI-2 link. Transitions may gate streaming or reconfigure
* link parameters. The host requests ownership changes via protocol opcodes
* and may need to assert GPIO signals on platforms without full capability.
*
* @ICVS_CSI_LINK_HOST: Host (Linux) owns the sensor and may start streaming
* @ICVS_CSI_LINK_CVS: CVS firmware owns the sensor (host must not stream)
*/
enum icvs_csi_link_owner {
ICVS_CSI_LINK_HOST,
ICVS_CSI_LINK_CVS,
};
/**
* enum icvs_csi_privacy_status - Reported privacy state
*
* Reflects user privacy (e.g. camera LED assertion and stream gating). The
* MAX value is a sentinel used for bounds checking and is not a real state.
*
* @ICVS_CSI_PRIVACY_OFF: Privacy not asserted (LED off, streaming permitted)
* @ICVS_CSI_PRIVACY_ON: Privacy asserted (LED on and/or stream gated)
* @ICVS_CSI_PRIVACY_MAX: Sentinel; not a valid operational value
*/
enum icvs_csi_privacy_status {
ICVS_CSI_PRIVACY_OFF,
ICVS_CSI_PRIVACY_ON,
ICVS_CSI_PRIVACY_MAX
};
/**
* enum icvs_csi_pads - Media pads exposed by the CVS sub-device
*
* The bridge presents a single sink (from the remote sensor) and a single
* source (toward the rest of the media graph / consumers). NUM_PADS is used
* for sizing arrays and iteration; it is not a real pad index.
*
* @ICVS_CSI_PAD_SINK: Sink pad receiving frames from remote sensor
* @ICVS_CSI_PAD_SOURCE: Source pad emitting frames to downstream entities
* @ICVS_CSI_NUM_PADS: Count sentinel (array size / iteration bound)
*/
enum icvs_csi_pads {
ICVS_CSI_PAD_SINK,
ICVS_CSI_PAD_SOURCE,
ICVS_CSI_NUM_PADS
};
/*
* Core driver structures and functions used by both I2C and platform modes
*/
/**
* DOC: CVS device quirk flags
*
* These bit flag macros describe per-device behavioral adjustments applied
* after VID/PID matching (see cvs_i2c_check() and cvs_apply_quirks()). They
* allow the driver to selectively alter logic paths for firmware / hardware
* variants without introducing hard-coded conditionals at each call site.
*
* @ICVS_NO_MIPI_CONFIG: Device firmware performs its own MIPI link setup;
* skip sending HOST_SET_MIPI_CONFIG.
* @ICVS_SKIP_FW_RESET: Skip issuing a post firmware-update reset sequence.
* @ICVS_NO_CAPS: Device firmware does not support GET_DEV_CAPABILITY;
* skip capability query and treat caps as unsupported.
* @ICVS_FW_BUF_SIZE_256: Firmware expects chunk transfer buffer size of 256
* bytes (override defaults if they differ).
* @ICVS_FW_HEADER_SIZE_256: Firmware header size fixed at 256 bytes offset
* for start of payload data.
* @ICVS_HOST_SENSOR_PWR_CTRL: Host must control sensor power sequencing.
* @ICVS_HOST_PRIV_CTRL: Host owns privacy LED gating.
* @ICVS_HOST_VISION_SENSING: Host enables vision sensing capability bit
* @ICVS_NO_FW_UPDATE: Device does not support firmware update.
*/
#define ICVS_NO_MIPI_CONFIG BIT(0)
#define ICVS_SKIP_FW_RESET BIT(1)
#define ICVS_NO_CAPS BIT(2)
#define ICVS_FW_BUF_SIZE_256 BIT(3)
#define ICVS_FW_HEADER_SIZE_256 BIT(4)
#define ICVS_HOST_SENSOR_PWR_CTRL BIT(5)
#define ICVS_HOST_PRIV_CTRL BIT(6)
#define ICVS_HOST_VISION_SENSING BIT(7)
#define ICVS_NO_FW_UPDATE BIT(8)
/**
* struct icvs_device_quirk - Device-specific quirk entry
* @vid: Vendor ID
* @pid: Product ID
* @quirks: Quirk flags for this device
*/
struct icvs_device_quirk {
u16 vid;
u16 pid;
unsigned long quirks;
};
/**
* struct icvs_dt_config - Data type configuration for a virtual channel
* @pixel_width: Pixel width in pixels
* @pixel_height: Pixel height in pixels
* @data_type: MIPI CSI-2 data type (RAW10, RAW12, etc.)
* @reserved: Reserved for future use
*/
struct icvs_dt_config {
u16 pixel_width;
u16 pixel_height;
u8 data_type;
u8 reserved[3];
};
/**
* struct icvs_vc_config - Virtual channel configuration
* @vc: Virtual channel index (0-31)
* @dt_count: Number of data types configured
* @dt_configs: Array of data type configurations (up to 4)
* @reserved: Reserved for future use
*/
struct icvs_vc_config {
u8 vc;
u8 dt_count;
struct icvs_dt_config dt_configs[4];
u8 reserved[6];
};
/**
* struct icvs_link_cfg - Host to CVS CSI link configuration
* @fps: Frames per second
* @nr_of_lanes: Number of CSI-2 data lanes used
* @phy_mode: 0 = DPHY, 1 = CPHY
* @vc_count: Number of virtual channels enabled
* @vc_configs: Per-VC configuration
* @link_freq: Link frequency in Hz
* @reserved: Reserved for future use
*/
struct icvs_link_cfg {
u8 fps;
u8 nr_of_lanes;
u8 phy_mode;
u8 vc_count;
struct icvs_vc_config vc_configs[4];
u32 link_freq;
u8 reserved[8];
};
/**
* struct icvs_fw_version - Firmware version tuple
* @major: Major version
* @minor: Minor version
* @hotfix: Hotfix/patch level
* @build: Build number
*/
struct icvs_fw_version {
u32 major;
u32 minor;
u32 hotfix;
u32 build;
};
/**
* struct icvs_vid_pid - Device vendor/product IDs
* @v_id: Vendor ID
* @p_id: Product ID
*/
struct icvs_vid_pid {
u16 v_id;
u16 p_id;
};
/**
* struct icvs_mipi_data_packet - Encapsulated MIPI link configuration packet
* @cmd_id: Command identifier
* @size: Payload size (bytes)
* @crc: Checksum over payload
* @conf: CSI link configuration
* @reserved: Reserved for future use
*/
struct icvs_mipi_data_packet {
__be16 cmd_id;
u32 size;
u32 crc;
struct icvs_link_cfg conf;
u8 reserved[70];
} __packed;
/**
* struct icvs_mipi_read_packet - Read-back MIPI configuration
* @size: Payload size
* @crc: Payload checksum
* @conf: CSI link configuration
*/
struct icvs_mipi_read_packet {
u32 size;
u32 crc;
struct icvs_link_cfg conf;
};
/* Host identifier bitfield masks */
#define ICVS_HOST_ID_RGBCAMERA_PWRUP BIT(31)
#define ICVS_HOST_ID_PRIVACY_LED BIT(30)
#define ICVS_HOST_ID_DEVICE_POWER GENMASK(29, 28)
#define ICVS_HOST_ID_VISION_SENSING BIT(27)
/* Device state bitfield masks (u8) */
#define ICVS_DEV_STATE_PRIVACY BIT(0)
#define ICVS_DEV_STATE_ON BIT(1)
#define ICVS_DEV_STATE_SENSOR_OWNER BIT(2)
#define ICVS_DEV_STATE_DOWNLOAD BIT(4)
#define ICVS_DEV_STATE_ERROR BIT(6)
#define ICVS_DEV_STATE_BUSY BIT(7)
/* Device capability bitfield masks (u16) */
#define ICVS_CAP_HOST_MIPI_REQUIRED BIT(15)
#define ICVS_CAP_FW_ANTIROLLBACK BIT(14)
#define ICVS_CAP_PRIVACY2VISIONDRIVER BIT(13)
#define ICVS_CAP_FWUPDATE_RESET_HOST BIT(12)
#define ICVS_CAP_NO_CAMERA_FWUPDATE BIT(11)
#define ICVS_CAP_POWER_DOMAIN_SUPPORT BIT(10)
#define ICVS_CAP_FW_FLASHED_IN_PLACE BIT(9)
#define ICVS_CAP_IO_CONTEXT_HOT BIT(8)
/**
* struct icvs_dev_capabilities - Protocol capabilities reported by device
* @protocol_version_major: Major protocol version
* @protocol_version_minor: Minor protocol version
* @capability: Capability bitfield - use ICVS_CAP_* masks
* @max_packet_time: Max packet processing time (ms)
* @max_post_dl_time: Max post-download time (s)
*/
struct icvs_dev_capabilities {
u8 protocol_version_major;
u8 protocol_version_minor;
u16 capability;
u16 max_packet_time;
u16 max_post_dl_time;
};
/**
* struct icvs_cmd - Generic command container
* @cmd_id: Command identifier
* @param: Parameter union providing multiple variants
* @param.param: Raw parameter
* @param.host_id: Host identifier (ICVS_SET_DEV_HOST_ID) - use
* ICVS_HOST_ID_* masks
* @param.conf: CSI link configuration (ICVS_HOST_SET_MIPI_CONFIG)
*/
struct icvs_cmd {
__be16 cmd_id;
union {
u32 param;
u32 host_id;
struct icvs_link_cfg conf;
} param;
} __packed;
/**
* struct icvs_resp - Firmware response container
* @status: Internal status code
* @cmd_id: Original command identifier
* @resp: Response union containing variant payload
* @resp.state: Device state response (u8, use ICVS_DEV_STATE_* masks)
* @resp.cap: Capability response
* @resp.conf: Link configuration response
* @resp.mipi_read: Raw link config read-back
* @resp.vid_pid: Vendor/product identifiers
* @resp.fw_version: Firmware version tuple
*/
struct icvs_resp {
u32 status;
__be16 cmd_id;
union {
u8 state;
struct icvs_dev_capabilities cap;
struct icvs_link_cfg conf;
struct icvs_mipi_read_packet mipi_read;
struct icvs_vid_pid vid_pid;
struct icvs_fw_version fw_version;
} resp;
};
/**
* enum icvs_resources - Device capability / resource category
*
* Categorizes hardware resource availability which influences protocol
* features (e.g. reset control, wake IRQ, GPIO mediated ownership). Light
* capability devices expose a reduced set of control GPIOs; full capability
* devices provide all optional signals and features. NOTSUP represents an
* unsupported or uninitialized state.
*
* @ICVS_NOTSUP: Capability not supported / not yet determined
* @ICVS_LIGHTCAP: Light capability (limited GPIO / no dedicated wake IRQ)
* @ICVS_FULLCAP: Full capability (reset GPIO, wake IRQ, extended protocol)
*/
enum icvs_resources {
ICVS_NOTSUP,
ICVS_LIGHTCAP,
ICVS_FULLCAP,
};
/**
* enum icvs_command - Protocol command opcodes (firmware space 0x0800+)
* @ICVS_GET_DEV_STATE: Query current device state bitfield
* @ICVS_GET_DEV_FW_VERSION: Retrieve firmware version tuple
* @ICVS_GET_DEV_VID_PID: Read vendor / product identifiers
* @ICVS_GET_DEV_ERR_CODE: Fetch last error code (if any)
* @ICVS_GET_DEV_CAPABILITY: Read protocol capability structure
* @ICVS_SET_DEV_HOST_ID: Set host identity / ownership bits
* @ICVS_GET_DEV_HOST_ID: Read back host identity
* @ICVS_FW_LOADER_START: Begin firmware download sequence
* @ICVS_FW_LOADER_DATA: Stream a chunk of firmware payload
* @ICVS_FW_LOADER_END: End firmware download / trigger flash
* @ICVS_HOST_GET_MIPI_CONFIG: Request current MIPI CSI link configuration
* @ICVS_HOST_SET_MIPI_CONFIG: Apply new MIPI CSI link configuration
* @ICVS_HOST_SENSOR_OWNER: Toggle CSI sensor ownership (GPIO assist)
*/
enum icvs_command {
ICVS_GET_DEV_STATE = 0x0800,
ICVS_GET_DEV_FW_VERSION = 0x0801,
ICVS_GET_DEV_VID_PID = 0x0802,
ICVS_GET_DEV_ERR_CODE = 0x0803,
ICVS_GET_DEV_CAPABILITY = 0x0804,
ICVS_SET_DEV_HOST_ID = 0x0805,
ICVS_GET_DEV_HOST_ID = 0x0806,
ICVS_FW_LOADER_START = 0x0820,
ICVS_FW_LOADER_DATA = 0x0821,
ICVS_FW_LOADER_END = 0x0822,
ICVS_HOST_GET_MIPI_CONFIG = 0x082F,
ICVS_HOST_SET_MIPI_CONFIG = 0x0830,
ICVS_HOST_SENSOR_OWNER = 0x0831,
};
/**
* enum icvs_state - Device state bitfield flags
*
* These flags correspond to bits in the device state byte returned via
* GET_DEV_STATE and decoded in union icvs_dev_state. Multiple bits may be
* asserted simultaneously. Reserved bits are omitted.
*
* @ICVS_DEVICE_OFF_STATE: Raw zero value; device is powered off or
* not yet ready
* @ICVS_DEVICE_PRIVACY_ON: Privacy mode active (LED asserted and/or
* stream gated)
* @ICVS_DEVICE_ON_STATE: Device powered and responsive to protocol commands
* @ICVS_DEVICE_SENSOR_OWNER: CVS currently owns the attached CSI sensor
* @ICVS_DEVICE_DWNLD_STATE: Firmware download / flash operation in progress
* @ICVS_DEVICE_ERROR_STATE: Device has reported an error (query
* ICVS_GET_DEV_ERR_CODE)
* @ICVS_DEVICE_BUSY_STATE: Device is busy processing a prior command
*/
enum icvs_state {
ICVS_DEVICE_OFF_STATE = 0x00,
ICVS_DEVICE_PRIVACY_ON = BIT(0),
ICVS_DEVICE_ON_STATE = BIT(1),
ICVS_DEVICE_SENSOR_OWNER = BIT(2),
ICVS_DEVICE_DWNLD_STATE = BIT(4),
ICVS_DEVICE_ERROR_STATE = BIT(6),
ICVS_DEVICE_BUSY_STATE = BIT(7),
};
/**
* struct icvs - Core CVS device context
* @i2c_client: I2C client (NULL in platform-only mode)
* @work: Delayed work for polling device state / completion
* @wq_resp: Last response container populated by workqueue
* @cmd_completion: Completion for command waiters
* @lock: Mutex protecting command submission & shared state
* @subdev: V4L2 sub-device representing the CSI bridge entity
* @remote: Remote media pad connected to upstream camera sensor
* @notifier: Async notifier for remote sensor discovery
* @ctrl_handler: V4L2 control handler
* @freq_ctrl: (future) frequency control pointer
* @pads: Local media pads (sink/source)
* @nr_of_lanes: Active CSI-2 lane count
* @ipu_link: PM runtime device link (IPU consumer, CVS supplier)
* @res: Resource capability (light/full)
* @caps: Reported device protocol capabilities
* @prefix: Firmware response prefix present
* @quirks: Device-specific quirk flags
* @rst: Reset GPIO (full capability only)
* @req: Request GPIO (ownership signaling)
* @resp: Response GPIO (ownership signaling)
* @irq: Wake IRQ (full capability)
* @hostwake_event: Waitqueue for wake events
* @hostwake_event_arg: Wake event flag
*/
struct icvs {
struct i2c_client *i2c_client;
struct delayed_work work;
struct icvs_resp wq_resp;
struct completion cmd_completion;
struct mutex lock; /* Protects command execution and device state */
struct v4l2_subdev subdev;
struct media_pad *remote;
struct v4l2_async_notifier notifier;
struct v4l2_ctrl_handler ctrl_handler;
struct v4l2_ctrl *freq_ctrl;
struct media_pad pads[ICVS_CSI_NUM_PADS];
u32 nr_of_lanes;
struct device_link *ipu_link;
enum icvs_resources res;
struct icvs_dev_capabilities caps;
bool prefix;
unsigned long quirks;
struct gpio_desc *rst;
struct gpio_desc *req;
struct gpio_desc *resp;
int irq;
wait_queue_head_t hostwake_event;
bool hostwake_event_arg;
};
/**
* cvs_dev - Helper returning the struct device for a CVS context
* @ctx: CVS context
*
* Avoids repeating transport conditional logic at each call site when
* acquiring the device pointer for logging or PM operations.
*
* Return: Device pointer (never NULL if @ctx is valid).
*/
static inline struct device *cvs_dev(struct icvs *ctx)
{
return ctx->i2c_client ? &ctx->i2c_client->dev : ctx->subdev.dev;
}
/* Cross-unit interfaces */
int cvs_send(struct icvs *ctx, struct icvs_cmd *cmd, size_t len);
int cvs_set_link_owner(struct icvs *ctx, enum icvs_csi_link_owner owner);
int cvs_csi_init(struct icvs *ctx, struct device *dev, struct i2c_client *i2c);
void cvs_csi_remove(struct icvs *ctx);
#endif /* _ICVS_H */
