/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2019, Joyent, Inc.
 */

#ifndef _SYS_USB_CCID_H
#define	_SYS_USB_CCID_H

/*
 * CCID class driver definitions.
 */

#include <sys/stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Values for various Hardware, Mechanical, and Pin features. These come from
 * the device's class descriptor.
 */
typedef enum ccid_class_voltage {
	CCID_CLASS_VOLT_AUTO	= 0x00,
	CCID_CLASS_VOLT_5_0	= 0x01,
	CCID_CLASS_VOLT_3_0	= 0x02,
	CCID_CLASS_VOLT_1_8	= 0x04
} ccid_class_voltage_t;

typedef enum ccid_class_mechanical {
	CCID_CLASS_MECH_CARD_ACCEPT	= 0x01,
	CCID_CLASS_MECH_CARD_EJECT	= 0x02,
	CCID_CLASS_MECH_CARD_CAPTURE	= 0x04,
	CCID_CLASS_MECH_CARD_LOCK	= 0x08
} ccid_class_mechanical_t;

typedef enum ccid_class_features {
	CCID_CLASS_F_AUTO_PARAM_ATR	= 0x00000002,
	CCID_CLASS_F_AUTO_ICC_ACTIVATE	= 0x00000004,
	CCID_CLASS_F_AUTO_ICC_VOLTAGE	= 0x00000008,
	CCID_CLASS_F_AUTO_ICC_CLOCK	= 0x00000010,
	CCID_CLASS_F_AUTO_BAUD		= 0x00000020,
	CCID_CLASS_F_AUTO_PARAM_NEG	= 0x00000040,
	CCID_CLASS_F_AUTO_PPS		= 0x00000080,
	CCID_CLASS_F_ICC_CLOCK_STOP	= 0x00000100,
	CCID_CLASS_F_ALTNAD_SUP		= 0x00000200,
	CCID_CLASS_F_AUTO_IFSD		= 0x00000400,
	CCID_CLASS_F_TPDU_XCHG		= 0x00010000,
	CCID_CLASS_F_SHORT_APDU_XCHG	= 0x00020000,
	CCID_CLASS_F_EXT_APDU_XCHG	= 0x00040000,
	CCID_CLASS_F_WAKE_UP		= 0x00100000
} ccid_class_features_t;

typedef enum ccid_class_pin {
	CCID_CLASS_PIN_VERIFICATION	= 0x01,
	CCID_CLASS_PIN_MODIFICATION	= 0x02
} ccid_class_pin_t;

/*
 * CCID Class Descriptor
 *
 * This structure represents the CCID class descriptor. Note, it should not be a
 * packed structure. This is designed to be a native representation. The raw
 * structure will be parsed into this instead.
 */
typedef struct ccid_class_descr {
	uint8_t		ccd_bLength;
	uint8_t		ccd_bDescriptorType;
	uint16_t	ccd_bcdCCID;
	uint8_t		ccd_bMaxSlotIndex;
	uint8_t		ccd_bVoltageSupport;
	uint32_t	ccd_dwProtocols;
	uint32_t	ccd_dwDefaultClock;
	uint32_t	ccd_dwMaximumClock;
	uint8_t		ccd_bNumClockSupported;
	uint32_t	ccd_dwDataRate;
	uint32_t	ccd_dwMaxDataRate;
	uint8_t		ccd_bNumDataRatesSupported;
	uint32_t	ccd_dwMaxIFSD;
	uint32_t	ccd_dwSyncProtocols;
	uint32_t	ccd_dwMechanical;
	uint32_t	ccd_dwFeatures;
	uint32_t	ccd_dwMaxCCIDMessageLength;
	uint8_t		ccd_bClassGetResponse;
	uint8_t		ccd_bClassEnvelope;
	uint16_t	ccd_wLcdLayout;
	uint8_t		ccd_bPinSupport;
	uint8_t		ccd_bMaxCCIDBusySlots;
} ccid_class_descr_t;

/*
 * Definitions for the supported versions of the CCID specification. The version
 * is encoded in binary encoded decimal. The major version is in the upper 8
 * bits and the minor version is in the lower 8 bits. We currently check for the
 * major version to match.
 */
#define	CCID_VERSION_MAJOR(ver)	(((ver) & 0xff00) >> 8)
#define	CCID_VERSION_MINOR(ver)	((ver) & 0x00ff)
#define	CCID_VERSION_ONE	0x01

/*
 * This structure is used as the data for the CCID_REQUEST_SET_PARAMS request
 * and the CCID_RESPONSE_PARAMETERS response. There are different structures for
 * T=0 and T=1. These come from CCID r1.1 / Section 6.1.7.
 */
typedef struct ccid_params_t0 {
	uint8_t cp0_bmFindexDindex;
	uint8_t cp0_bmTCCKST0;
	uint8_t cp0_bGuardTimeT0;
	uint8_t cp0_bWaitingIntegerT0;
	uint8_t	cp0_bClockStop;
} __packed ccid_params_t0_t;

#define	CCID_P_TCCKST0_DIRECT	0x00
#define	CCID_P_TCCKST0_INVERSE	0x02

typedef struct ccid_params_t1 {
	uint8_t cp1_bmFindexDindex;
	uint8_t cp1_bmTCCKST1;
	uint8_t cp1_bGuardTimeT1;
	uint8_t cp1_bmWaitingIntegersT1;
	uint8_t cp1_bClockStop;
	uint8_t cp1_bIFSC;
	uint8_t cp1_bNadValue;
} __packed ccid_params_t1_t;

typedef union ccid_params {
	ccid_params_t0_t ccp_t0;
	ccid_params_t1_t ccp_t1;
} ccid_params_t;

#define	CCID_P_FI_DI(fi, di)	((((fi) & 0x0f) << 4) | ((di) & 0x0f))

/*
 * Everything below this point is reserved for the kernel.
 */
#ifdef	_KERNEL

/*
 * These values come from CCID r1.1.0 Table 5.1-1 'Smart Card Device
 * Descriptors'
 */
#define	CCID_DESCR_TYPE		0x21
#define	CCID_DESCR_LENGTH	0x36


/*
 * Minimum and maximum value for a sequence number in the CCID specification.
 * The sequence is a 1 byte unsigned value. The values are inclusive. We reserve
 * the value of 0x00 so that we can use it as a sentinel in the ccid_command_t
 * structure to know when we should or shouldn't free a command structure's
 * sequence number back to the id space.
 */
#define	CCID_SEQ_MIN	0x01
#define	CCID_SEQ_MAX	UINT8_MAX


/*
 * All structures from the specification must be packed.
 */

/*
 * Interrupt-IN messages codes.
 */
typedef enum ccid_intr_code {
	CCID_INTR_CODE_SLOT_CHANGE	= 0x50,
	CCID_INTR_CODE_HW_ERROR		= 0x51
} ccid_intr_code_t;

typedef enum ccid_intr_hwerr_code {
	CCID_INTR_HWERR_OVERCURRENT	= 0x01
} ccid_intr_hwerr_code_t;

typedef struct ccid_intr_slot {
	uint8_t	cis_type;
	uint8_t	cis_state[];
} ccid_intr_slot_t;

typedef struct ccid_intr_hwerr {
	uint8_t	cih_type;
	uint8_t	cih_slot;
	uint8_t	cih_seq;
	uint8_t	cih_code;
} ccid_intr_hwerr_t;

/*
 * Message request codes. These codes are based on CCID r1.1.0 Table 6.1-1
 * 'Summary of Bulk-Out Messages'. The name from the standard is to the right of
 * the enum.
 */
typedef enum ccid_request_code {
	CCID_REQUEST_POWER_ON		= 0x62,	/* PC_to_RDR_IccPowerOn */
	CCID_REQUEST_POWER_OFF		= 0x63,	/* PC_to_RDR_IccPowerOff */
	CCID_REQUEST_SLOT_STATUS	= 0x65,	/* PC_to_RDR_GetSlotStatus */
	CCID_REQUEST_TRANSFER_BLOCK	= 0x6f,	/* PC_to_RDR_XfrBlock */
	CCID_REQUEST_GET_PARAMS		= 0x6c,	/* PC_to_RDR_GetParameters */
	CCID_REQUEST_RESET_PARAMS	= 0x6d,	/* PC_to_RDR_ResetParameters */
	CCID_REQUEST_SET_PARAMS		= 0x61,	/* PC_to_RDR_SetParameters */
	CCID_REQUEST_ESCAPE		= 0x6b,	/* PC_to_RDR_Escape */
	CCID_REQUEST_ICC_CLOCK		= 0x6e,	/* PC_to_RDR_IccClock */
	CCID_REQUEST_T0APDU		= 0x6a,	/* PC_to_RDR_T0APDU */
	CCID_REQUEST_SECURE		= 0x69,	/* PC_to_RDR_Secure */
	CCID_REQUEST_MECHANICAL		= 0x71,	/* PC_to_RDR_Mechanica */
	CCID_REQEUST_ABORT		= 0x72,	/* PC_to_RDR_Abort */
	CCID_REQUEST_DATA_CLOCK		= 0x73	/* PC_to_RDR_SetDataRateAnd */
						/* ClockFrequency */
} ccid_request_code_t;

/*
 * Message request codes. These codes are based on CCID r1.1.0 Table 6.2-1
 * 'Summary of Bulk-In Messages'. The name from the standard is to the right of
 * the enum.
 */
typedef enum ccid_response_code {
	CCID_RESPONSE_DATA_BLOCK	= 0x80,	/* RDR_to_PC_DataBlock */
	CCID_RESPONSE_SLOT_STATUS	= 0x81,	/* RDR_to_PC_SlotStatus */
	CCID_RESPONSE_PARAMETERS	= 0x82, /* RDR_to_PC_Parameters */
	CCID_RESPONSE_ESCAPE		= 0x83,	/* RDR_to_PC_Escape */
	CCID_RESPONSE_DATA_CLOCK	= 0x84	/* RDR_to_PC_DataRateAnd */
						/* ClockFrequency */
} ccid_response_code_t;

/*
 * This represents the CCID command header that is used for every request and
 * response.
 */
typedef struct ccid_header {
	uint8_t		ch_mtype;
	uint32_t	ch_length;	/* Length of ch_data in bytes */
	uint8_t		ch_slot;	/* CCID slot to target */
	uint8_t		ch_seq;		/* Request/Response sequence num */
	uint8_t		ch_param0;	/* Request/Response specific */
	uint8_t		ch_param1;	/* Request/Response specific */
	uint8_t		ch_param2;	/* Request/Response specific */
	uint8_t		ch_data[];	/* Optional Request/Response Data */
} __packed ccid_header_t;

/*
 * This structure is used as the data for the CCID_REQUEST_DATA_CLOCK and
 * CCID_RESPONSE_DATA_CLOCK commands.
 */
typedef struct ccid_data_clock {
	uint32_t	cdc_clock;
	uint32_t	cdc_data;
} __packed ccid_data_clock_t;

/*
 * Macros and constants to take apart the slot status (in ch_param1) when a CCID
 * reply comes in.
 */
#define	CCID_REPLY_ICC(x)	(x & 0x3)
#define	CCID_REPLY_STATUS(x)	((x & 0xc0) >> 6)

typedef enum {
	CCID_REPLY_ICC_ACTIVE = 0,
	CCID_REPLY_ICC_INACTIVE,
	CCID_REPLY_ICC_MISSING
} ccid_reply_icc_status_t;

typedef enum {
	CCID_REPLY_STATUS_COMPLETE = 0,
	CCID_REPLY_STATUS_FAILED,
	CCID_REPLY_STATUS_MORE_TIME
} ccid_reply_command_status_t;

/*
 * Errors that are defined based when commands fail. These are based on CCID
 * r.1.1.0 Table 6.2-2 'Slot error register when bmCommandStatus = 1'.
 */
typedef enum ccid_command_err {
	CCID_ERR_CMD_ABORTED			= 0xff,
	CCID_ERR_ICC_MUTE			= 0xfe,
	CCID_ERR_XFR_PARITY_ERROR		= 0xfd,
	CCID_ERR_XFR_OVERRUN			= 0xfc,
	CCID_ERR_HW_ERROR			= 0xfb,
	CCID_ERR_BAD_ATR_TS			= 0xf8,
	CCID_ERR_BAD_ATR_TCK			= 0xf7,
	CCID_ERR_ICC_PROTOCOL_NOT_SUPPORTED	= 0xf6,
	CCID_ERR_ICC_CLASS_NOT_SUPPORTED	= 0xf5,
	CCID_ERR_PROCEDURE_BYTE_CONFLICT	= 0xf4,
	CCID_ERR_DEACTIVATED_PROTOCOL		= 0xf3,
	CCID_ERR_BUSY_WITH_AUTO_SEQUENCE	= 0xf2,
	CCID_ERR_PIN_TIMEOUT			= 0xf0,
	CCID_ERR_PIN_CANCELLED			= 0xef,
	CCID_ERR_CMD_SLOT_BUSY			= 0xe0,
	CCID_ERR_CMD_NOT_SUPPORTED		= 0x00
} ccid_command_err_t;

/*
 * Maximum size of an APDU (application data unit) payload. There are both short
 * and extended ADPUs. At this time, we only support the short ADPUs.
 */
#define	CCID_APDU_LEN_MAX	261

#endif	/* _KERNEL */

#ifdef __cplusplus
}
#endif

#endif /* _SYS_USB_CCID_H */