From 11ddfabb7229f1d00f9c5d5ca94595dbab904682 Mon Sep 17 00:00:00 2001 From: philipchen Date: Sat, 3 Dec 2016 16:28:43 -0800 Subject: [PATCH] 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 Tested-by: Philip Chen Reviewed-by: Shawn N --- common/charge_manager.c | 84 ++++++++++++++------------------------- include/charge_manager.h | 86 ++++++++++++++++++++++++++++++++-------- 2 files changed, 99 insertions(+), 71 deletions(-) diff --git a/common/charge_manager.c b/common/charge_manager.c index 9d5df6184a..1c9bac377e 100644 --- a/common/charge_manager.c +++ b/common/charge_manager.c @@ -92,6 +92,9 @@ enum charge_manager_change_type { * PD communication is not allowed, so we must assume that it is dedicated. * Also, if no battery is present, the charger may be our only source of power, * so again we must assume that the charger is dedicated. + * + * @return 1 when we need to override the a non-dedicated charger + * to be a dedicated one, 0 otherwise. */ static int charge_manager_spoof_dualrole_capability(void) { @@ -131,8 +134,10 @@ static void charge_manager_init(void) DECLARE_HOOK(HOOK_INIT, charge_manager_init, HOOK_PRIO_CHARGE_MANAGER_INIT); /** - * Returns 1 if all ports + suppliers have reported in with some initial charge, - * 0 otherwise. + * Check if the charge manager is seeded. + * + * @return 1 if all ports/suppliers have reported + * with some initial charge, 0 otherwise. */ static int charge_manager_is_seeded(void) { @@ -156,6 +161,12 @@ static int charge_manager_is_seeded(void) } #ifndef TEST_BUILD +/** + * Get the maximum charge current for a port. + * + * @param port Charge port. + * @return Charge current (mA). + */ static int charge_manager_get_source_current(int port) { switch (source_port_last_rp[port]) { @@ -171,6 +182,9 @@ static int charge_manager_get_source_current(int port) /** * Fills passed power_info structure with current info about the passed port. + * + * @param port Charge port. + * @param r USB PD power info to be updated. */ static void charge_manager_fill_power_info(int port, struct ec_response_usb_pd_power_info *r) @@ -345,6 +359,8 @@ void charge_manager_save_log(int port) /** * Attempt to switch to power source on port if applicable. + * + * @param port USB-C port to be swapped. */ static void charge_manager_switch_to_source(int port) { @@ -369,7 +385,6 @@ static int charge_manager_get_ceil(int port) int ceil = CHARGE_CEIL_NONE; int val, i; - ASSERT(port >= 0 && port < CONFIG_USB_PD_PORT_COUNT); for (i = 0; i < CEIL_REQUESTOR_COUNT; ++i) { val = charge_ceil[port][i]; if (val != CHARGE_CEIL_NONE && @@ -383,6 +398,9 @@ static int charge_manager_get_ceil(int port) /** * Select the 'best' charge port, as defined by the supplier heirarchy and the * ability of the port to provide power. + * + * @param new_port Pointer to the best charge port by definition. + * @param new_supplier Pointer to the best charge supplier by definition. */ static void charge_manager_get_best_charge_port(int *new_port, int *new_supplier) @@ -659,6 +677,14 @@ static void charger_detect_debounced(void) } DECLARE_DEFERRED(charger_detect_debounced); +/** + * Update charge parameters for a given port / supplier. + * + * @param change Type of change. + * @param supplier Charge supplier to be updated. + * @param port Charge port to be updated. + * @param charge Charge port current / voltage. + */ static void charge_manager_make_change(enum charge_manager_change_type change, int supplier, int port, @@ -761,33 +787,15 @@ static void charge_manager_make_change(enum charge_manager_change_type change, hook_call_deferred(&charge_manager_refresh_data, 0); } -/** - * Update available charge for a given port / supplier. - * - * @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) { - ASSERT(supplier >= 0 && supplier < CHARGE_SUPPLIER_COUNT); - ASSERT(port >= 0 && port < CONFIG_USB_PD_PORT_COUNT); - ASSERT(charge != NULL); - charge_manager_make_change(CHANGE_CHARGE, supplier, port, charge); } -/** - * 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) { - ASSERT(port >= 0 && port < CONFIG_USB_PD_PORT_COUNT); if (charge_manager_spoof_dualrole_capability()) cap = CAP_DEDICATED; @@ -799,19 +807,8 @@ void charge_manager_update_dualrole(int port, enum dualrole_capabilities cap) } } -/** - * 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) { - ASSERT(port >= 0 && port < CONFIG_USB_PD_PORT_COUNT && - requestor >= 0 && requestor < CEIL_REQUESTOR_COUNT); - if (charge_ceil[port][requestor] != ceil) { charge_ceil[port][requestor] = ceil; if (port == charge_port && charge_manager_is_seeded()) @@ -838,21 +835,10 @@ void charge_manager_force_ceil(int port, int ceil) charge_manager_set_ceil(port, CEIL_REQUESTOR_PD, ceil); } -/** - * Select an 'override port', a port which is always the preferred charge port. - * Returns EC_SUCCESS on success, ec_error_list status on failure. - * - * @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. - */ int charge_manager_set_override(int port) { int retval = EC_SUCCESS; - ASSERT(port >= OVERRIDE_DONT_CHARGE && port < CONFIG_USB_PD_PORT_COUNT); - CPRINTS("Charge Override: %d", port); /* @@ -893,12 +879,6 @@ int charge_manager_set_override(int port) return retval; } -/** - * Get the override port. OVERRIDE_OFF if no override port. - * OVERRIDE_DONT_CHARGE if override is set for no port. - * - * @return override port - */ int charge_manager_get_override(void) { return override_port; @@ -909,17 +889,11 @@ int charge_manager_get_active_charge_port(void) return charge_port; } -/** - * Return the charger current (mA) value. - */ int charge_manager_get_charger_current(void) { return charge_current; } -/** - * Return the power limit (uW) set by charge manager. - */ int charge_manager_get_power_limit_uw(void) { int current_ma = charge_current; 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.