path: root/include/sound/sdca_function.h

/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause) */
/*
 * The MIPI SDCA specification is available for public downloads at
 * https://www.mipi.org/mipi-sdca-v1-0-download
 *
 * Copyright(c) 2024 Intel Corporation
 */

#ifndef __SDCA_FUNCTION_H__
#define __SDCA_FUNCTION_H__

#include <linux/bits.h>
#include <linux/types.h>
#include <linux/hid.h>

struct device;
struct sdca_entity;
struct sdca_function_desc;

#define SDCA_NO_INTERRUPT -1

/*
 * The addressing space for SDCA relies on 7 bits for Entities, so a
 * maximum of 128 Entities per function can be represented.
 */
#define SDCA_MAX_ENTITY_COUNT 128

/*
 * Sanity check on number of initialization writes, can be expanded if needed.
 */
#define SDCA_MAX_INIT_COUNT 2048

/*
 * The Cluster IDs are 16-bit, so a maximum of 65535 Clusters per
 * function can be represented, however limit this to a slightly
 * more reasonable value. Can be expanded if needed.
 */
#define SDCA_MAX_CLUSTER_COUNT 256

/*
 * Sanity check on number of channels per Cluster, can be expanded if needed.
 */
#define SDCA_MAX_CHANNEL_COUNT 32

/*
 * Sanity check on number of PDE delays, can be expanded if needed.
 */
#define SDCA_MAX_DELAY_COUNT 256

/*
 * Sanity check on size of affected controls data, can be expanded if needed.
 */
#define SDCA_MAX_AFFECTED_COUNT 2048

/**
 * enum sdca_function_type - SDCA Function Type codes
 * @SDCA_FUNCTION_TYPE_SMART_AMP: Amplifier with protection features.
 * @SDCA_FUNCTION_TYPE_SIMPLE_AMP: Subset of SmartAmp.
 * @SDCA_FUNCTION_TYPE_SMART_MIC: Smart microphone with acoustic triggers.
 * @SDCA_FUNCTION_TYPE_SIMPLE_MIC: Subset of SmartMic.
 * @SDCA_FUNCTION_TYPE_SPEAKER_MIC: Combination of SmartMic and SmartAmp.
 * @SDCA_FUNCTION_TYPE_UAJ: 3.5mm Universal Audio jack.
 * @SDCA_FUNCTION_TYPE_RJ: Retaskable jack.
 * @SDCA_FUNCTION_TYPE_SIMPLE_JACK: Subset of UAJ.
 * @SDCA_FUNCTION_TYPE_HID: Human Interface Device, for e.g. buttons.
 * @SDCA_FUNCTION_TYPE_IMP_DEF: Implementation-defined function.
 *
 * SDCA Function Types from SDCA specification v1.0a Section 5.1.2
 * all Function types not described are reserved.
 *
 * Note that SIMPLE_AMP, SIMPLE_MIC and SIMPLE_JACK Function Types
 * are NOT defined in SDCA 1.0a, but they were defined in earlier
 * drafts and are planned for 1.1.
 */
enum sdca_function_type {
	SDCA_FUNCTION_TYPE_SMART_AMP			= 0x01,
	SDCA_FUNCTION_TYPE_SIMPLE_AMP			= 0x02,
	SDCA_FUNCTION_TYPE_SMART_MIC			= 0x03,
	SDCA_FUNCTION_TYPE_SIMPLE_MIC			= 0x04,
	SDCA_FUNCTION_TYPE_SPEAKER_MIC			= 0x05,
	SDCA_FUNCTION_TYPE_UAJ				= 0x06,
	SDCA_FUNCTION_TYPE_RJ				= 0x07,
	SDCA_FUNCTION_TYPE_SIMPLE_JACK			= 0x08,
	SDCA_FUNCTION_TYPE_HID				= 0x0A,
	SDCA_FUNCTION_TYPE_IMP_DEF			= 0x1F,
};

/* Human-readable names used for kernel logs and Function device registration/bind */
#define	SDCA_FUNCTION_TYPE_SMART_AMP_NAME		"SmartAmp"
#define	SDCA_FUNCTION_TYPE_SIMPLE_AMP_NAME		"SimpleAmp"
#define	SDCA_FUNCTION_TYPE_SMART_MIC_NAME		"SmartMic"
#define	SDCA_FUNCTION_TYPE_SIMPLE_MIC_NAME		"SimpleMic"
#define	SDCA_FUNCTION_TYPE_SPEAKER_MIC_NAME		"SpeakerMic"
#define	SDCA_FUNCTION_TYPE_UAJ_NAME			"UAJ"
#define	SDCA_FUNCTION_TYPE_RJ_NAME			"RJ"
#define	SDCA_FUNCTION_TYPE_SIMPLE_NAME			"SimpleJack"
#define	SDCA_FUNCTION_TYPE_HID_NAME			"HID"
#define	SDCA_FUNCTION_TYPE_IMP_DEF_NAME			"ImplementationDefined"

/**
 * struct sdca_init_write - a single initialization write
 * @addr: Register address to be written
 * @val: Single byte value to be written
 */
struct sdca_init_write {
	u32 addr;
	u8 val;
};

/**
 * define SDCA_CTL_TYPE - create a unique identifier for an SDCA Control
 * @ent: Entity Type code.
 * @sel: Control Selector code.
 *
 * Sometimes there is a need to identify a type of Control, for example to
 * determine what name the control should have. SDCA Selectors are reused
 * across Entity types, as such it is necessary to combine both the Entity
 * Type and the Control Selector to obtain a unique identifier.
 */
#define SDCA_CTL_TYPE(