diff options
author | philipchen <philipchen@google.com> | 2016-12-03 16:28:43 -0800 |
---|---|---|
committer | chrome-bot <chrome-bot@chromium.org> | 2016-12-06 15:58:34 -0800 |
commit | 11ddfabb7229f1d00f9c5d5ca94595dbab904682 (patch) | |
tree | 80965db6bc678dfb40553ced2d82d7d9928fc266 /include/charge_manager.h | |
parent | d0af9df60552aecd2ea308753c25ea607f217fe8 (diff) | |
download | chrome-ec-11ddfabb7229f1d00f9c5d5ca94595dbab904682.tar.gz |
charge_manager: cleanup and document
Remove some runtime assert to reduce code size.
Improve the documentation.
BUG=chromium:670886
BRANCH=none
TEST=make buildall -j
Change-Id: I60bd787fad94779cd978aefa26e0581fb5f6ebef
Reviewed-on: https://chromium-review.googlesource.com/416392
Commit-Ready: Philip Chen <philipchen@chromium.org>
Tested-by: Philip Chen <philipchen@chromium.org>
Reviewed-by: Shawn N <shawnn@chromium.org>
Diffstat (limited to 'include/charge_manager.h')
-rw-r--r-- | include/charge_manager.h | 86 |
1 files changed, 70 insertions, 16 deletions
diff --git a/include/charge_manager.h b/include/charge_manager.h index 1082883445..64c8272886 100644 --- a/include/charge_manager.h +++ b/include/charge_manager.h @@ -17,7 +17,7 @@ #define CHARGE_CURRENT_UNINITIALIZED -1 #define CHARGE_VOLTAGE_UNINITIALIZED -1 -/* +/** * Time to delay for detecting the charger type (must be long enough for BC1.2 * driver to get supplier information and notify charge manager). */ @@ -42,7 +42,13 @@ struct charge_port_info { int voltage; }; -/* Called by charging tasks to update their available charge */ +/** + * Called by charging tasks to update their available charge. + * + * @param supplier Charge supplier to update. + * @param port Charge port to update. + * @param charge Charge port current / voltage. + */ void charge_manager_update_charge(int supplier, int port, struct charge_port_info *charge); @@ -54,10 +60,15 @@ enum dualrole_capabilities { CAP_DEDICATED, }; -/* Called by charging tasks to indicate partner dualrole capability change */ +/** + * Notify charge_manager of a partner dualrole capability change. + * + * @param port Charge port which changed. + * @param cap New port capability. + */ void charge_manager_update_dualrole(int port, enum dualrole_capabilities cap); -/* +/** * Charge ceiling can be set independently by different tasks / functions, * for different purposes. */ @@ -70,7 +81,14 @@ enum ceil_requestor { CEIL_REQUESTOR_COUNT, }; -/* Update charge ceiling for a given port / requestor */ +/** + * Update charge ceiling for a given port. The ceiling can be set independently + * for several requestors, and the min. ceil will be enforced. + * + * @param port Charge port to update. + * @param requestor Charge ceiling requestor. + * @param ceil Charge ceiling (mA). + */ void charge_manager_set_ceil(int port, enum ceil_requestor requestor, int ceil); /* @@ -83,17 +101,44 @@ void charge_manager_set_ceil(int port, enum ceil_requestor requestor, int ceil); */ void charge_manager_force_ceil(int port, int ceil); -/* Select an 'override port', which is always the preferred charge port */ +/** + * Select an 'override port', a port which is always the preferred charge port. + * + * @param port Charge port to select as override, or + * OVERRIDE_OFF to select no override port, + * or OVERRIDE_DONT_CHARGE to specific that no + * charge port should be selected. + * @return EC_SUCCESS on success, + * the other ec_error_list status on failure. + */ int charge_manager_set_override(int port); + +/** + * Get the override port. + * + * @return Port number or OVERRIDE_OFF or OVERRIDE_DONT_CHARGE. + */ int charge_manager_get_override(void); -/* Returns the current active charge port, as determined by charge manager */ +/** + * Get the current active charge port, as determined by charge manager. + * + * @return Current active charge port. + */ int charge_manager_get_active_charge_port(void); -/* Return the power limit (uW) set by charge manager. */ +/** + * Get the power limit set by charge manager. + * + * @return Power limit (uW). + */ int charge_manager_get_power_limit_uw(void); -/* Return the charger current (mA) value or CHARGE_CURRENT_UNINITIALIZED. */ +/** + * Get the charger current (mA) value. + * + * @return Charger current (mA) or CHARGE_CURRENT_UNINITIALIZED. + */ int charge_manager_get_charger_current(void); #ifdef CONFIG_USB_PD_LOGGING @@ -101,10 +146,16 @@ int charge_manager_get_charger_current(void); void charge_manager_save_log(int port); #endif -/* Update whether a given port is sourcing current. */ +/** + * Update whether a given port is sourcing current. + * + * @param port Port number to be updated. + * @param enable 0 if the source port is disabled; + * Otherwise the source port is enabled. + */ void charge_manager_source_port(int port, int enable); -/* +/** * Get PD source power data objects. * * @param src_pdo pointer to the data to return. @@ -114,13 +165,16 @@ int charge_manager_get_source_pdo(const uint32_t **src_pdo); /* Board-level callback functions */ -/* - * Set the active charge port. Returns EC_SUCCESS if the charge port is - * accepted, returns ec_error_list status otherwise. +/** + * Set the passed charge port as active.` + * + * @param charge_port Charge port to be enabled. + * @return EC_SUCCESS if the charge port is accepted, + * other ec_error_list status otherwise. */ int board_set_active_charge_port(int charge_port); -/* +/** * Set the charge current limit. * * @param port PD port. @@ -132,7 +186,7 @@ int board_set_active_charge_port(int charge_port); void board_set_charge_limit(int port, int supplier, int charge_ma, int max_ma, int charge_mv); -/* +/** * Get whether the port is sourcing power on VBUS. * * @param port PD port. |