Browse Source

Document the functions in struct pdb_dpm_callbacks

Clara Hobbs 7 years ago
parent
commit
b7670f4367
1 changed files with 87 additions and 6 deletions
  1. 87
    6
      lib/include/pdb_dpm.h

+ 87
- 6
lib/include/pdb_dpm.h View File

@@ -37,22 +37,103 @@ typedef bool (*pdb_dpm_giveback_func)(struct pdb_config *);
37 37
 typedef bool (*pdb_dpm_tcc_func)(struct pdb_config *, enum fusb_typec_current);
38 38
 
39 39
 /*
40
- * PD Buddy firmware library device policy manager callback structure
40
+ * PD Buddy firmware library Device Policy Manager callbacks
41
+ *
42
+ * All functions are passed a struct pdb_config * as their first parameter.
43
+ * This points to the struct pdb_config that contains the calling thread.
41 44
  *
42 45
  * Optional functions may be set to NULL if the associated functionality is not
43 46
  * required.
44 47
  */
45 48
 struct pdb_dpm_callbacks {
49
+    /*
50
+     * Evaluate the Source_Capabilities, creating a Request in response.
51
+     *
52
+     * The second parameter is the Source_Capabilities message.  This is NULL
53
+     * when the function is called as a result of the PDB_EVT_PE_NEW_POWER
54
+     * event.
55
+     *
56
+     * The third parameter is a union pd_msg * into which the Request must be
57
+     * written.
58
+     *
59
+     * Returns true if sufficient power is available, false otherwise.
60
+     */
46 61
     pdb_dpm_eval_cap_func evaluate_capability;
62
+
63
+    /*
64
+     * Create a Sink_Capabilities message for our current capabilities.
65
+     *
66
+     * The second parameter is a union pd_msg * into which the
67
+     * Sink_Capabilities message must be written.
68
+     */
47 69
     pdb_dpm_get_sink_cap_func get_sink_capability;
48
-    pdb_dpm_giveback_func giveback_enabled; /* Optional (missing means no GiveBack) */
49
-    pdb_dpm_tcc_func evaluate_typec_current; /* Optional (missing means no Type-C Current) */
50
-    pdb_dpm_func pd_start; /* Optional */
70
+
71
+    /*
72
+     * Return whether or not GiveBack support is enabled.
73
+     *
74
+     * Optional.  If the implementation does not support GiveBack under any
75
+     * circumstances, this may be omitted.
76
+     */
77
+    pdb_dpm_giveback_func giveback_enabled;
78
+
79
+    /*
80
+     * Evaluate whether or not the Type-C Current can fulfill our power needs.
81
+     *
82
+     * The second parameter is an enum fusb_typec_current holding the Type-C
83
+     * Current level to evaluate.
84
+     *
85
+     * Returns true if sufficient power is available, false otherwise.
86
+     *
87
+     * Optional.  If the implementation does not require Type-C Current support
88
+     * (e.g. more than 5 V is required for the device to function), this may be
89
+     * omitted.
90
+     */
91
+    pdb_dpm_tcc_func evaluate_typec_current;
92
+
93
+    /*
94
+     * Called at the start of Power Delivery negotiations.
95
+     *
96
+     * Optional.  If nothing special needs to happen when PD negotiations
97
+     * start, this may be omitted.
98
+     */
99
+    pdb_dpm_func pd_start;
100
+
101
+    /*
102
+     * Transition the sink to the default power level for USB.
103
+     */
51 104
     pdb_dpm_func transition_default;
52
-    pdb_dpm_func transition_min; /* Optional if no GiveBack */
105
+
106
+    /*
107
+     * Transition to the requested minimum current.
108
+     *
109
+     * Optional.  If and only if giveback_enabled is NULL, this may be omitted.
110
+     */
111
+    pdb_dpm_func transition_min;
112
+
113
+    /*
114
+     * Transition to Sink Standby if necessary.
115
+     *
116
+     * From section 7.2.3 of the USB PD spec, the sink shall reduce its
117
+     * power draw to no more than 2.5 W before a positive or negative
118
+     * transition of Vbus.  This function must determine if a voltage
119
+     * transition is occurring, and if it is, it must reduce the power
120
+     * consumption to the required level.
121
+     */
53 122
     pdb_dpm_func transition_standby;
123
+
124
+    /*
125
+     * Transition to the requested power level.
126
+     */
54 127
     pdb_dpm_func transition_requested;
55
-    pdb_dpm_func transition_typec; /* Optional if no Type-C Current */
128
+
129
+    /*
130
+     * Transition to the appropriate power level for the most recent Type-C
131
+     * Current evaluated.
132
+     *
133
+     * Optional.  If and only if evaluate_typec_current is NULL, this may be
134
+     * omitted.
135
+     */
136
+    pdb_dpm_func transition_typec;
56 137
 };
57 138
 
58 139
 

Loading…
Cancel
Save