【UCSI】USB Type-C Connector System Software Interface

	关于UCSI的相关文档可以通过如下链接下载，本文章仅作为介绍，如有侵权请联系删除。
	https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/usb-type-c-ucsi-spec.pdf

1. 简介

	USB Type-C连接器系统软件接口(UCSI) 描述了用于与系统上的带有USB Type-C接头接口的寄存器和数据结构。

2. 角色

	OS Policy Manager(OPM)---它是一个操作系统策略管理器，专门负责与PPM对接的。
	Platform Policy Manager(PPM)---管理所有Type-C connector的硬件/软件。
	USB Type-C policy Manager(TCPM)---USB Type-C管理器，负责管理一个或多个USB Type-C端口的上层策略。
	Connector---Type-C port。

3. 数据结构

	在OPM跟PPM之间存在信息传递，而信息的存储器结构如下表所示。
	OPM->PPM表示OPM使用内存位置将信息传递给PPM。就PPM而言，位置为只读（RO）。
	PPM->OPM表示PPM使用内存位置将信息传递给OPM。就OPM而言，位置是只读（RO）。

Offset(Bytes)	Mnemonic	Memory Location Name	Direction	Size(bits)
0	VERSION	UCSI Version Number	PPM->OPM	16
2	RESERVED	Reserved	N/A	16
4	CCI	USB Type-C Command Status and Connector Change Indication	PPM->OPM	32
8	CONTROL	USB Type-C Control	OPM->PPM	64
16	MESSAGE IN	USB Type-C Message In	PPM->OPM	128
32	MESSAGE OUT	USB Type-C Message Out	OPM->PPM	128

3.1 VERSION

	VERSION---指PPM遵循的UCSI规范的BCD版本。PPM在通电或复位后立即更新此数据。对于版本JJ.M.N(JJ-主版本号，M-次版本号，N-子版本号)，
版本数据结构的值为0xJJMN，例如版本2.1.3用0x0213表示，版本3.0用0x0300表示。

3.2 CCI

	CCI---USB Type-C命令状态和连接器改变指示。OPM通过该部分数据来告知OPM，针对OPM下发的命令，PPM完成的情况以及指示MESSAGE In
中有效数据的位数。

Offset(Bits)	Field	Size(Bits)	Description
0	Reserved	1	Reserved and shall be set to zero.
1	Connector Change Indicator	7	The PPM shall use this field to indicate the connector number that a change occurred on. Valid values are 0 to the maximum number of connectors supported on the platform. If this field is set to zero, then no change occurred on any of the connectors.
8	Data Length	8	Length of valid data in bytes. If this value is greater than zero then the MESSAGE IN Data Structure contents are valid. The value in this register shall be less than or equal to MAX_DATA_LENGTH(16 Bytes).
16	Reserved	9	Reserved and shall be set to zero.
25	Not Supported Indicator	1	The PPM shall set this field to one when it wants to indicate that it does not currently support a command. This field shall only be valid when the Command Completed Indicator field is set to one.
26	Cancel Completed Indicator	1	The PPM shall set this field to one when it has completed a CANCEL command. This field shall only be valid when the Command Completed Indicator field is set to one.
27	Reset Completed Indicator	1	The PPM shall set this field to one when it has completed a PPM_RESET command. If this field is set to one, then no other bits in this Data Structure shall be set by the PPM. The PPM shall clear this field on reception of the next command (not PPM_RESET) from the OPM.
28	Busy Indicator	1	The PPM shall set this field to one when it wants to indicate that the PPM is currently busy and will complete the command sent to it by the OPM at a later time. If this field is set to one, then no other bits in this Data Structure shall be set by the PPM. When the PPM completes the command sent to it, it shall set this field to zero and update the other fields in this Data Structure appropriately before notifying the OPM.
29	Acknowledge Command Indicator	1	The PPM shall set this field to one when it completes the ACK_CC_CI (Acknowledge Command Completion and/or Change Indication) command. The PPM shall automatically reset this bit when it receives the next command from the OPM. If this field is set to one, then the only other field that can be set is the Connector Change Indicator field.
30	Error Indicator	1	The PPM shall set this field to one when it encounters an error when executing the command sent to it by the OPM.This field shall only be valid when the Command Completed Indicator field is set to one.
31	Command Completed Indicator	1	The PPM shall set this field to one when it wants to indicate that it completed the command sent to it by the OPM.

3.3 CONTROL

	USB Type-C Control Data---该部分用来指示OPM想要PPM执行的命令。

Offset(Bits)	Field	Size(Bits)	Description
0	Command	8	The value in this field determines the command that OPM wants the PPM to execute. Bits 16-63 shall contain any parameters specific to this command.
8	Data Length	8	Length of valid data in bytes. If this value is greater than zero then the MESSAGE OUT Data Structure contents are valid. The value in this field shall be less than or equal to MAX_DATA_LENGTH(16 bytes).
16	Command Specific	48	The definition of these bits is different for each command that can be sent to the PPM.

	OPM想要PPM执行的命令主要有以下这些：
	R---request
	O---optional

Command	Index	Function	R/O
PPM RESET	0x01	Reset the PPM	R
CANCEL	0x02	Cancel a command previously sent to the PPM.	R
Connector Reset	0x03	Reset the connector specified	R
Acknowledge Command Completion and/or Change Indication	0x04	Acknowledge to the PPM that the OPM received and processed a Command Completion and/or a Connector Change Indication.	R
Set Notification Enable	0x05	Set the list of asynchronous events that the PPM may send notifications about to the OPM.	R
Get Capability	0x06	Get the PPM capabilities.	R
Get Connector Capability	0x07	Get the capabilities of a connector.	R
Set CC Operation Mode	0x08	Set the CC operation mode that the OPM wants the connector to operate at.	O
Set USB Operation Role	0x09	Set the USB operation role that the OPM wants the connector to operate at, for the current connection.	R
Set Power Direction Role	0x0B	Set the Power direction that the OPM wants the connector to operate at, for the current connection.	R
Get Alternate Modes	0x0C	Get the Alternate Modes that the Connector/Cable/Attached Device is capable of supporting.	O
Get Connector Alternate Modes Supported	0x0D	Get the list of Alternate Modes that are currently supported on the connector identified.	O
Get Current Connector Alternate Mode	0x0E	Get the current Alternate Mode that the connector is operating in.	O
Set New Connector Alternate Mode	0x0F	Set the new Alternate Mode that the OPM wants the PPM to operate in.	O
Get PDOs	0x10	Get the Sink or Source PDOs associated with the connector identified.	O
Get Cable Property	0x11	Get the Cable properties on the connector identified.	O
Get Connector Status	0x12	Get the current status of the connector identified by this command.	R
Get Error Status	0x13	Get details about an error, if one is reported by the PPM.	R

3.4 MESSAGE IN

	MESSAGE IN数据包含PPM想要发送到OPM的数据。该数据会根据命令的不同而有所不同。只有当收到PPM已完成命令的通知时，OPM才应从该数据结构中读取。
PPM只能在响应要求返回数据的命令（来自OPM）时写入该数据结构。如果PPM需要返回数据，则应在通知OPM之前写入该数据结构。

3.5 MESSAGE OUT

	MESSAGE OUT数据包含要发送到PPM的数据。该数据会根据命令的不同而有所不同。只有当PPM没有执行有效命令时，OPM才应写入该数据结构。只有当发送
给PPM的命令（来自OPM）定义数据应存在于该数据结构中时，PPM才应从该数据结构读取。

4. 上下层交互流程

	完整的一个交互流程是需要EC、BIOS、UCSI driver一起参与的。BIOS在期间的作用主要是告诉driver哪一块内存是专门给到UCSI使用的，并且将UCSI 
driver驱动的命令下发给EC。下面内容主要是站在EC的角度进行讲述。
	下面两张图片是来自UCSI Spec中关于PPM的状态机。

4.1 初始化流程

	在EC刚上电初始化完成之后，要进行UCSI参数的初始化，其中包括写明UCSI使用的版本号以及清空Notification Enable的所有值，然后处于Idle(no 
notification enable)，在该状态下，仅能处理SET_NOTIFICATION_ENABLE和PPM_RESET两条CMD，其余的不允许处理。之后在UCSI driver准备好之后
会发起如下流程来对PPM进行初始化。
	1. OPM发送PPM_RESET命令去要求复位PPM；PPM完成之后回复一个Reset_Completed_Indicator的CCI
	2. OPM发送SET_NOTIFICATION_ENABLE命令，指示PPM可以进行command completed的notification；然后PPM回复一个Command completed的CCI
	3. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	4. OPM发送GET_CAPABILITY命令去获取PPM的能力；PPM填写完自身能力的MESSAGE OUT之后，然后PPM回复一个指示MESSAGE OUT的长度和Command 
completed的CCI
	5. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	6. OPM发送GET_CONNECTOR_CAPABILITY命令去获取其中一个connector的能力；PPM填写完OPM指定的port的能力的MESSAGE OUT之后，回复一个指示
MESSAGE OUT的长度、哪一个port和command completed的CCI
	7. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	8. OPM发送GET_CONNECTOR_CAPABILITY命令去获取其中一个connector的能力；PPM填写完OPM指定的port的能力的MESSAGE OUT之后，回复一个指示
MESSAGE OUT的长度、哪一个port和command completed的CCI
	9. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	10. OPM发送GET_CONNECTOR_STATUS命令去获取其中一个connector当前的状态；PPM填写完OPM指定port的状态的MESSAGE OUT之后，回复一个指示
MESSAGE OUT的长度、哪一个port和command completed的CCI
	11.OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	12. OPM发送GET_CONNECTOR_STATUS命令去获取其中一个connector当前的状态；PPM填写完OPM指定port的状态的MESSAGE OUT之后，回复一个指示
MESSAGE OUT的长度、哪一个port和command completed的CCI
	13. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI
	14. OPM发送SET_NOTIFICATION_ENABLE命令去enable PPM其他的notification；然后PPM回复一个Command completed的CCI
	15. OPM发送ACK_CMD_CC_CI命令，表示OPM收到并完成了命令处理；然后PPM回复一个Command completed的CCI

	注意：在第4步的时候，PPM回复的MESSAGE IN中含有了本机器包含几个Type-C port，后续的GET_CONNECTOR_CAPABILITY和GET_CONNECTOR_STATUS
的数量与之对应。上述示例是以回复具有2个Type-C ports所举的样例。

4.2 正常沟通流程

	在日常使用过程中，OPM与PPM发生的最多的沟通就是在我们插拔Type-C port时，OPM来获取connector的状态。具体流程如下：
	在PD拉取EC的INT之后，EC去读取PD相关的registers，然后判断是否Connector Status发生改变，如果是，则更新好CCI(告知是哪个port发生变化)并通知
OPM来获取。OPM获取完之后会发送GET_CONNECTOR_STATUS的命令来获取具体变更的事项。