1 /*
2  * Copyright (C) 2022 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.hardware.usb;
18 
19 import android.Manifest;
20 import android.annotation.CheckResult;
21 import android.annotation.IntDef;
22 import android.annotation.NonNull;
23 import android.annotation.RequiresPermission;
24 import android.annotation.SystemApi;
25 import android.os.Parcel;
26 import android.os.Parcelable;
27 
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.RetentionPolicy;
30 import java.util.Objects;
31 
32 /**
33  * Holds information related to DisplayPort Alt Mode statuses
34  *
35  * @hide
36  */
37 @SystemApi
38 public final class DisplayPortAltModeInfo implements Parcelable {
39     private final @DisplayPortAltModeStatus int mPartnerSinkStatus;
40     private final @DisplayPortAltModeStatus int mCableStatus;
41     private final int mNumLanes;
42     private final boolean mHotPlugDetect;
43     private final @LinkTrainingStatus int mLinkTrainingStatus;
44 
45     /**
46      * Port Partners:
47      * The port partner status is currently unknown for one of the following reasons:
48      *     <ul>
49      *     <li> No port partner is connected to the device
50      *     <li> The USB Power Delivery Discover Identity command has not been issued to the port
51      *     partner via SOP messaging.
52      *     </ul>
53      * <p>
54      * Cables:
55      * The cable’s capabilities are not yet known to the device, or no cable is plugged in.
56      */
57     public static final int DISPLAYPORT_ALT_MODE_STATUS_UNKNOWN = 0;
58 
59     /**
60      * Port Partners:
61      * The current port partner does not list DisplayPort as one of its Alt Modes, or does not list
62      * the capability to act as a DisplayPort Source or Sink device, or a compatible configuration
63      * could not be established.
64      * <p>
65      * Cables:
66      * The cable/adapter’s capabilities do not list DisplayPort as one of its Alt Modes, or a
67      * compatible configuration could not be established.
68      */
69     public static final int DISPLAYPORT_ALT_MODE_STATUS_NOT_CAPABLE = 1;
70 
71     /**
72      * Port Partners:
73      * The current port partner lists compatible DisplayPort capabilities with the device, however
74      * may not yet have entered DisplayPort Alt Mode or has configured its port for data
75      * transmission.
76      * <p>
77      * Cables:
78      * The Type-C cable/adapter’s capabilities have been discovered and list DisplayPort Alt Mode
79      * as one of its capabilities, however may not yet have entered DisplayPort Alt Mode or has been
80      * configured for data transmission.
81      */
82     public static final int DISPLAYPORT_ALT_MODE_STATUS_CAPABLE_DISABLED = 2;
83 
84     /**
85      * Port Partners:
86      * The port partner and device are both configured for DisplayPort Alt Mode.
87      * <p>
88      * Cables:
89      * The Type-C cable/adapter is configured for DisplayPort Alt Mode.
90      */
91     public static final int DISPLAYPORT_ALT_MODE_STATUS_ENABLED = 3;
92 
93     /*
94      * Indicates that DisplayPort Alt Mode link training has not initiated or completed.
95      */
96     public static final int LINK_TRAINING_STATUS_UNKNOWN = 0;
97 
98     /*
99      * Indicates that DisplayPort Alt Mode link training has completed and the optimal data
100      * transmission settings between the device and the connected port partner have successfully
101      * been negotiated.
102      */
103     public static final int LINK_TRAINING_STATUS_SUCCESS = 1;
104 
105     /*
106      * Indicates that DisplayPort Alt Mode link training has completed but no data transmission
107      * settings between the device and the connected port partner could be established, and that the
108      * link initialization has terminated.
109      */
110     public static final int LINK_TRAINING_STATUS_FAILURE = 2;
111 
112     /** @hide */
113     @IntDef(prefix = { "DISPLAYPORT_ALT_MODE_STATUS_" }, value = {
114             DISPLAYPORT_ALT_MODE_STATUS_UNKNOWN,
115             DISPLAYPORT_ALT_MODE_STATUS_NOT_CAPABLE,
116             DISPLAYPORT_ALT_MODE_STATUS_CAPABLE_DISABLED,
117             DISPLAYPORT_ALT_MODE_STATUS_ENABLED,
118     })
119     @Retention(RetentionPolicy.SOURCE)
120     public @interface DisplayPortAltModeStatus {}
121 
122     /** @hide */
123     @IntDef(prefix = { "LINK_TRAINING_STATUS_" }, value = {
124             LINK_TRAINING_STATUS_UNKNOWN,
125             LINK_TRAINING_STATUS_SUCCESS,
126             LINK_TRAINING_STATUS_FAILURE,
127     })
128     @Retention(RetentionPolicy.SOURCE)
129     public @interface LinkTrainingStatus {}
130 
131     /** @hide */
DisplayPortAltModeInfo()132     public DisplayPortAltModeInfo() {
133         mPartnerSinkStatus = DISPLAYPORT_ALT_MODE_STATUS_UNKNOWN;
134         mCableStatus = DISPLAYPORT_ALT_MODE_STATUS_UNKNOWN;
135         mNumLanes = 0;
136         mHotPlugDetect = false;
137         mLinkTrainingStatus = LINK_TRAINING_STATUS_UNKNOWN;
138     }
139 
140     /** @hide */
DisplayPortAltModeInfo(int partnerSinkStatus, int cableStatus, int numLanes, boolean hotPlugDetect, int linkTrainingStatus)141     public DisplayPortAltModeInfo(int partnerSinkStatus, int cableStatus,
142             int numLanes, boolean hotPlugDetect, int linkTrainingStatus) {
143         mPartnerSinkStatus = partnerSinkStatus;
144         mCableStatus = cableStatus;
145         mNumLanes = numLanes;
146         mHotPlugDetect = hotPlugDetect;
147         mLinkTrainingStatus = linkTrainingStatus;
148     }
149 
150     /**
151      * Returns the DisplayPort Alt Mode Status for a port partner acting as a sink.
152      *
153      */
getPartnerSinkStatus()154     public @DisplayPortAltModeStatus int getPartnerSinkStatus() {
155         return mPartnerSinkStatus;
156     }
157 
158     /**
159      * Returns the DisplayPort Alt Mode Status for the attached cable
160      *
161      */
getCableStatus()162     public @DisplayPortAltModeStatus int getCableStatus() {
163         return mCableStatus;
164     }
165 
166     /**
167      * Returns the number of lanes used to transmit display data.
168      *
169      */
getNumberOfLanes()170     public int getNumberOfLanes() {
171         return mNumLanes;
172     }
173 
174     /**
175      * Returns whether or not the Hot Plug Detect (HPD) value of the connected DisplayPort Alt Mode
176      * partner sink is active.
177      */
isHotPlugDetectActive()178     public boolean isHotPlugDetectActive() {
179         return mHotPlugDetect;
180     }
181 
182     /**
183      * Returns the DisplayPort Alt Mode link training status.
184      */
getLinkTrainingStatus()185     public @LinkTrainingStatus int getLinkTrainingStatus() {
186         return mLinkTrainingStatus;
187     }
188 
189     @Override
describeContents()190     public int describeContents() {
191         return 0;
192     }
193 
194     @Override
writeToParcel(@onNull Parcel dest, int flags)195     public void writeToParcel(@NonNull Parcel dest, int flags) {
196         dest.writeInt(mPartnerSinkStatus);
197         dest.writeInt(mCableStatus);
198         dest.writeInt(mNumLanes);
199         dest.writeBoolean(mHotPlugDetect);
200         dest.writeInt(mLinkTrainingStatus);
201     }
202 
displayPortAltModeStatusToString(@isplayPortAltModeStatus int status)203     private String displayPortAltModeStatusToString(@DisplayPortAltModeStatus int status) {
204         switch (status) {
205             case DISPLAYPORT_ALT_MODE_STATUS_NOT_CAPABLE:
206                 return "not capable";
207             case DISPLAYPORT_ALT_MODE_STATUS_CAPABLE_DISABLED:
208                 return "capable disabled";
209             case DISPLAYPORT_ALT_MODE_STATUS_ENABLED:
210                 return "enabled";
211             default:
212                 return "unknown";
213         }
214     }
215 
linkTrainingStatusToString(@inkTrainingStatus int status)216     private String linkTrainingStatusToString(@LinkTrainingStatus int status) {
217         switch (status) {
218             case LINK_TRAINING_STATUS_SUCCESS:
219                 return "success";
220             case LINK_TRAINING_STATUS_FAILURE:
221                 return "failure";
222             default:
223                 return "unknown";
224         }
225     }
226 
227     @NonNull
228     @Override
toString()229     public String toString() {
230         return "DisplayPortAltModeInfo{partnerSink="
231                 + displayPortAltModeStatusToString(mPartnerSinkStatus)
232                 + ", cable="
233                 + displayPortAltModeStatusToString(mCableStatus)
234                 + ", numLanes="
235                 + mNumLanes
236                 + ", hotPlugDetect="
237                 + mHotPlugDetect
238                 + ", linkTrainingStatus="
239                 + linkTrainingStatusToString(mLinkTrainingStatus)
240                 + "}";
241     }
242 
243     @Override
equals(Object o)244     public boolean equals(Object o) {
245         if (this == o) {
246             return true;
247         }
248         if (!(o instanceof DisplayPortAltModeInfo)) {
249             return false;
250         }
251         DisplayPortAltModeInfo other = (DisplayPortAltModeInfo) o;
252         return this.mPartnerSinkStatus == other.mPartnerSinkStatus
253                 && this.mCableStatus == other.mCableStatus
254                 && this.mNumLanes == other.mNumLanes
255                 && this.mHotPlugDetect == other.mHotPlugDetect
256                 && this.mLinkTrainingStatus == other.mLinkTrainingStatus;
257     }
258 
259     @Override
hashCode()260     public int hashCode() {
261         return Objects.hash(mPartnerSinkStatus, mCableStatus, mNumLanes, mHotPlugDetect,
262                 mLinkTrainingStatus);
263     }
264 
265     public static final @NonNull Parcelable.Creator<DisplayPortAltModeInfo> CREATOR =
266             new Parcelable.Creator<DisplayPortAltModeInfo>() {
267         @Override
268         public DisplayPortAltModeInfo createFromParcel(Parcel in) {
269             int partnerSinkStatus = in.readInt();
270             int cableStatus = in.readInt();
271             int numLanes = in.readInt();
272             boolean hotPlugDetect = in.readBoolean();
273             int linkTrainingStatus = in.readInt();
274             return new DisplayPortAltModeInfo(partnerSinkStatus, cableStatus, numLanes,
275                     hotPlugDetect, linkTrainingStatus);
276         }
277 
278         @Override
279         public DisplayPortAltModeInfo[] newArray(int size) {
280             return new DisplayPortAltModeInfo[size];
281         }
282     };
283 }
284