platform/chrome: cros_ec_proto: update cros_ec_check_result() comment
Subsystems (2)
Tzung-Bi Shih
maintainerPATCH 1/1 platform/chrome: cros_ec_proto: update cros_ec_check_result() comment
At first glance, cros_ec_check_result() is quite like cros_ec_map_error(). They check for ec_msg->result and return corresponding errors. However, as calling from pkt_xfer and cmd_xfer, cros_ec_check_result() should not report furthermore errors. -EAGAIN is the only exception.
See [1][2][3] for some known userland programs' code. The return code from ioctl only denotes the EC communication status. Userland programs would further analyze the result in struct cros_ec_command* for follow-up actions (e.g. [4]).
To clarify, update the function comment.
[1]: https://crrev.com/54400e93a75ef440a83d6eaac2cec066daf99cf0/util/comm-dev.c#154
[2]: https://crrev.com/fe32670a89bf59e1aff84bba9dd3295657b85e9b/cros_ec_dev.c#296
[3]: https://crrev.com/5952a561abaeed1491294a33883d6fd2c2c4089f/drivers/google/cros_ec_dev.c#120
[4]: https://crrev.com/54400e93a75ef440a83d6eaac2cec066daf99cf0/util/comm-dev.c#164
---
Also see commit 57b888ca2541 ("platform/chrome: Re-introduce cros_ec_cmd_xfer and use it for ioctls") in for-next branch for some other details.
The patch bases on the latest for-kernelci branch.
(https://git.kernel.org/pub/scm/linux/kernel/git/chrome-platform/linux.git/commit/?h=for-kernelci&id=0534c15c9291a0d571d813fa7c54358736d9ef4c)
drivers/platform/chrome/cros_ec_proto.c | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
drivers/platform/chrome/cros_ec_proto.c +5 -2
@@ -199,9 +199,12 @@ EXPORT_SYMBOL(cros_ec_prepare_tx);* @msg: Message to check. * * This is used by ChromeOS EC drivers to check the ec_msg->result for -* errors and to warn about them. +* EC_RES_IN_PROGRESS and to warn about them. * -* Return: 0 on success or negative error code. +* The function should not check for furthermore error codes. Otherwise, +* it would break the ABI. +* +* Return: -EAGAIN if ec_msg->result == EC_RES_IN_PROGRESS. Otherwise, 0. */ int cros_ec_check_result (struct cros_ec_device *ec_dev,struct cros_ec_command *msg)
base-commit: 0534c15c9291a0d571d813fa7c54358736d9ef4c
Signature · 1 line
2.36.0.550.gb090851708-goog
Tzung-Bi Shih
maintainerQuoted 11 lines · Tzung-Bi Shih
At first glance,
cros_ec_check_result()is quite likecros_ec_map_error(). They check forec_msg->resultand return corresponding errors. However, as calling frompkt_xferandcmd_xfer,cros_ec_check_result()should not report furthermore errors.-EAGAINis the only exception.See [1][2][3] for some known userland programs' code. The return code from ioctl only denotes the EC communication status. Userland programs would further analyze the
resultin struct cros_ec_command* for follow-up actions (e.g. [4]).To clarify, update the function comment.
Pardon me if it is confusing. The patch now merged into a series in order to make more sense. Let's ignore the patch and move discussion to [5] if any.
[5]: https://patchwork.kernel.org/project/chrome-platform/patch/[email protected]/