Commit c9b46568 authored by Gwendal Grignou's avatar Gwendal Grignou Committed by Enric Balletbo i Serra
Browse files

platform/chrome: cros_ec: Put docs with the code 



To avoid doc rot, put function documentations with code, not header.
Use kernel-doc style comments for exported functions.

Signed-off-by: default avatarGwendal Grignou <gwendal@chromium.org>
Acked-by: default avatarJonathan Cameron <Jonathan.Cameron@huawei.com>
Signed-off-by: default avatarEnric Balletbo i Serra <enric.balletbo@collabora.com>
parent 54ecb8f7

drivers/platform/chrome/cros_ec.c

+33 −0
Original line number Diff line number Diff line
@@ -104,6 +104,15 @@ static int cros_ec_sleep_event(struct cros_ec_device *ec_dev, u8 sleep_event) 
	return ret;

}



/**

 * cros_ec_register() - Register a new ChromeOS EC, using the provided info.

 * @ec_dev: Device to register.

 *

 * Before calling this, allocate a pointer to a new device and then fill

 * in all the fields up to the --private-- marker.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_register(struct cros_ec_device *ec_dev)

{

	struct device *dev = ec_dev->dev;
@@ -198,6 +207,14 @@ int cros_ec_register(struct cros_ec_device *ec_dev) 
}

EXPORT_SYMBOL(cros_ec_register);



/**

 * cros_ec_unregister() - Remove a ChromeOS EC.

 * @ec_dev: Device to unregister.

 *

 * Call this to deregister a ChromeOS EC, then clean up any private data.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_unregister(struct cros_ec_device *ec_dev)

{

	if (ec_dev->pd)
@@ -209,6 +226,14 @@ int cros_ec_unregister(struct cros_ec_device *ec_dev) 
EXPORT_SYMBOL(cros_ec_unregister);



#ifdef CONFIG_PM_SLEEP

/**

 * cros_ec_suspend() - Handle a suspend operation for the ChromeOS EC device.

 * @ec_dev: Device to suspend.

 *

 * This can be called by drivers to handle a suspend event.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_suspend(struct cros_ec_device *ec_dev)

{

	struct device *dev = ec_dev->dev;
@@ -243,6 +268,14 @@ static void cros_ec_report_events_during_suspend(struct cros_ec_device *ec_dev) 
					     1, ec_dev);

}



/**

 * cros_ec_resume() - Handle a resume operation for the ChromeOS EC device.

 * @ec_dev: Device to resume.

 *

 * This can be called by drivers to handle a resume event.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_resume(struct cros_ec_device *ec_dev)

{

	int ret;

drivers/platform/chrome/cros_ec_proto.c

+70 −0
Original line number Diff line number Diff line
@@ -117,6 +117,17 @@ static int send_command(struct cros_ec_device *ec_dev, 
	return ret;

}



/**

 * cros_ec_prepare_tx() - Prepare an outgoing message in the output buffer.

 * @ec_dev: Device to register.

 * @msg: Message to write.

 *

 * This is intended to be used by all ChromeOS EC drivers, but at present

 * only SPI uses it. Once LPC uses the same protocol it can start using it.

 * I2C could use it now, with a refactor of the existing code.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_prepare_tx(struct cros_ec_device *ec_dev,

		       struct cros_ec_command *msg)

{
@@ -141,6 +152,16 @@ int cros_ec_prepare_tx(struct cros_ec_device *ec_dev, 
}

EXPORT_SYMBOL(cros_ec_prepare_tx);



/**

 * cros_ec_check_result() - Check ec_msg->result.

 * @ec_dev: EC device.

 * @msg: Message to check.

 *

 * This is used by ChromeOS EC drivers to check the ec_msg->result for

 * errors and to warn about them.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_check_result(struct cros_ec_device *ec_dev,

			 struct cros_ec_command *msg)

{
@@ -326,6 +347,13 @@ static int cros_ec_get_host_command_version_mask(struct cros_ec_device *ec_dev, 
	return ret;

}



/**

 * cros_ec_query_all() -  Query the protocol version supported by the

 *         ChromeOS EC.

 * @ec_dev: Device to register.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_query_all(struct cros_ec_device *ec_dev)

{

	struct device *dev = ec_dev->dev;
@@ -453,6 +481,16 @@ exit: 
}

EXPORT_SYMBOL(cros_ec_query_all);



/**

 * cros_ec_cmd_xfer() - Send a command to the ChromeOS EC.

 * @ec_dev: EC device.

 * @msg: Message to write.

 *

 * Call this to send a command to the ChromeOS EC.  This should be used

 * instead of calling the EC's cmd_xfer() callback directly.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_cmd_xfer(struct cros_ec_device *ec_dev,

		     struct cros_ec_command *msg)

{
@@ -500,6 +538,18 @@ int cros_ec_cmd_xfer(struct cros_ec_device *ec_dev, 
}

EXPORT_SYMBOL(cros_ec_cmd_xfer);



/**

 * cros_ec_cmd_xfer_status() - Send a command to the ChromeOS EC.

 * @ec_dev: EC device.

 * @msg: Message to write.

 *

 * This function is identical to cros_ec_cmd_xfer, except it returns success

 * status only if both the command was transmitted successfully and the EC

 * replied with success status. It's not necessary to check msg->result when

 * using this function.

 *

 * Return: The number of bytes transferred on success or negative error code.

 */

int cros_ec_cmd_xfer_status(struct cros_ec_device *ec_dev,

			    struct cros_ec_command *msg)

{
@@ -584,6 +634,16 @@ static int get_keyboard_state_event(struct cros_ec_device *ec_dev) 
	return ec_dev->event_size;

}



/**

 * cros_ec_get_next_event() - Fetch next event from the ChromeOS EC.

 * @ec_dev: Device to fetch event from.

 * @wake_event: Pointer to a bool set to true upon return if the event might be

 *              treated as a wake event. Ignored if null.

 *

 * Return: negative error code on errors; 0 for no data; or else number of

 * bytes received (i.e., an event was retrieved successfully). Event types are

 * written out to @ec_dev->event_data.event_type on success.

 */

int cros_ec_get_next_event(struct cros_ec_device *ec_dev, bool *wake_event)

{

	u8 event_type;
@@ -628,6 +688,16 @@ int cros_ec_get_next_event(struct cros_ec_device *ec_dev, bool *wake_event) 
}

EXPORT_SYMBOL(cros_ec_get_next_event);



/**

 * cros_ec_get_host_event() - Return a mask of event set by the ChromeOS EC.

 * @ec_dev: Device to fetch event from.

 *

 * When MKBP is supported, when the EC raises an interrupt, we collect the

 * events raised and call the functions in the ec notifier. This function

 * is a helper to know which events are raised.

 *

 * Return: 0 on error or non-zero bitmask of one or more EC_HOST_EVENT_*.

 */

u32 cros_ec_get_host_event(struct cros_ec_device *ec_dev)

{

	u32 host_event;

include/linux/platform_data/cros_ec_proto.h

+0 −103
Original line number Diff line number Diff line
@@ -187,133 +187,30 @@ struct cros_ec_platform { 
	u16 cmd_offset;

};



/**

 * cros_ec_suspend() - Handle a suspend operation for the ChromeOS EC device.

 * @ec_dev: Device to suspend.

 *

 * This can be called by drivers to handle a suspend event.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_suspend(struct cros_ec_device *ec_dev);



/**

 * cros_ec_resume() - Handle a resume operation for the ChromeOS EC device.

 * @ec_dev: Device to resume.

 *

 * This can be called by drivers to handle a resume event.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_resume(struct cros_ec_device *ec_dev);



/**

 * cros_ec_prepare_tx() - Prepare an outgoing message in the output buffer.

 * @ec_dev: Device to register.

 * @msg: Message to write.

 *

 * This is intended to be used by all ChromeOS EC drivers, but at present

 * only SPI uses it. Once LPC uses the same protocol it can start using it.

 * I2C could use it now, with a refactor of the existing code.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_prepare_tx(struct cros_ec_device *ec_dev,

		       struct cros_ec_command *msg);



/**

 * cros_ec_check_result() - Check ec_msg->result.

 * @ec_dev: EC device.

 * @msg: Message to check.

 *

 * This is used by ChromeOS EC drivers to check the ec_msg->result for

 * errors and to warn about them.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_check_result(struct cros_ec_device *ec_dev,

			 struct cros_ec_command *msg);



/**

 * cros_ec_cmd_xfer() - Send a command to the ChromeOS EC.

 * @ec_dev: EC device.

 * @msg: Message to write.

 *

 * Call this to send a command to the ChromeOS EC.  This should be used

 * instead of calling the EC's cmd_xfer() callback directly.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_cmd_xfer(struct cros_ec_device *ec_dev,

		     struct cros_ec_command *msg);



/**

 * cros_ec_cmd_xfer_status() - Send a command to the ChromeOS EC.

 * @ec_dev: EC device.

 * @msg: Message to write.

 *

 * This function is identical to cros_ec_cmd_xfer, except it returns success

 * status only if both the command was transmitted successfully and the EC

 * replied with success status. It's not necessary to check msg->result when

 * using this function.

 *

 * Return: The number of bytes transferred on success or negative error code.

 */

int cros_ec_cmd_xfer_status(struct cros_ec_device *ec_dev,

			    struct cros_ec_command *msg);



/**

 * cros_ec_register() - Register a new ChromeOS EC, using the provided info.

 * @ec_dev: Device to register.

 *

 * Before calling this, allocate a pointer to a new device and then fill

 * in all the fields up to the --private-- marker.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_register(struct cros_ec_device *ec_dev);



/**

 * cros_ec_unregister() - Remove a ChromeOS EC.

 * @ec_dev: Device to unregister.

 *

 * Call this to deregister a ChromeOS EC, then clean up any private data.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_unregister(struct cros_ec_device *ec_dev);



/**

 * cros_ec_query_all() -  Query the protocol version supported by the

 *         ChromeOS EC.

 * @ec_dev: Device to register.

 *

 * Return: 0 on success or negative error code.

 */

int cros_ec_query_all(struct cros_ec_device *ec_dev);



/**

 * cros_ec_get_next_event() - Fetch next event from the ChromeOS EC.

 * @ec_dev: Device to fetch event from.

 * @wake_event: Pointer to a bool set to true upon return if the event might be

 *              treated as a wake event. Ignored if null.

 *

 * Return: negative error code on errors; 0 for no data; or else number of

 * bytes received (i.e., an event was retrieved successfully). Event types are

 * written out to @ec_dev->event_data.event_type on success.

 */

int cros_ec_get_next_event(struct cros_ec_device *ec_dev, bool *wake_event);



/**

 * cros_ec_get_host_event() - Return a mask of event set by the ChromeOS EC.

 * @ec_dev: Device to fetch event from.

 *

 * When MKBP is supported, when the EC raises an interrupt, we collect the

 * events raised and call the functions in the ec notifier. This function

 * is a helper to know which events are raised.

 *

 * Return: 0 on error or non-zero bitmask of one or more EC_HOST_EVENT_*.

 */

u32 cros_ec_get_host_event(struct cros_ec_device *ec_dev);



#endif /* __LINUX_CROS_EC_PROTO_H */

CRA Git | Maintained and supported by SUSTech CRA and CCSE