Commit e2bbf91c authored by Enric Balletbo i Serra's avatar Enric Balletbo i Serra Committed by Benson Leung
Browse files

mfd: cros_ec: Fix and improve kerneldoc comments. 



cros-ec includes inside the MFD subsystem, specially the file
cros_ec_commands.h, has been modified several times and it has grown a
lot, unfortunately, we didn't have care too much about the documentation.
This patch tries to improve the documentation and also fixes all the
issues reported by kerneldoc script.

Signed-off-by: default avatarEnric Balletbo i Serra <enric.balletbo@collabora.com>
Signed-off-by: default avatarBenson Leung <bleung@chromium.org>
parent cc8a4ea1

drivers/mfd/cros_ec_dev.h

+7 −6
Original line number Diff line number Diff line
@@ -26,12 +26,13 @@ 


#define CROS_EC_DEV_VERSION "1.0.0"



/*

 * @offset: within EC_LPC_ADDR_MEMMAP region

 * @bytes: number of bytes to read. zero means "read a string" (including '\0')

 *         (at most only EC_MEMMAP_SIZE bytes can be read)

 * @buffer: where to store the result

 * ioctl returns the number of bytes read, negative on error

/**

 * struct cros_ec_readmem - Struct used to read mapped memory.

 * @offset: Within EC_LPC_ADDR_MEMMAP region.

 * @bytes: Number of bytes to read. Zero means "read a string" (including '\0')

 *         At most only EC_MEMMAP_SIZE bytes can be read.

 * @buffer: Where to store the result. The ioctl returns the number of bytes

 *         read or negative on error.

 */

struct cros_ec_readmem {

	uint32_t offset;

include/linux/mfd/cros_ec.h

+113 −101
Original line number Diff line number Diff line
@@ -36,7 +36,7 @@ 
 * I2C requires 1 additional byte for requests.

 * I2C requires 2 additional bytes for responses.

 * SPI requires up to 32 additional bytes for responses.

 * */

 */

#define EC_PROTO_VERSION_UNKNOWN	0

#define EC_MAX_REQUEST_OVERHEAD		1

#define EC_MAX_RESPONSE_OVERHEAD	32
@@ -58,13 +58,14 @@ enum { 
	EC_MAX_MSG_BYTES		= 64 * 1024,

};



/*

 * @version: Command version number (often 0)

 * @command: Command to send (EC_CMD_...)

 * @outsize: Outgoing length in bytes

 * @insize: Max number of bytes to accept from EC

 * @result: EC's response to the command (separate from communication failure)

 * @data: Where to put the incoming data from EC and outgoing data to EC

/**

 * struct cros_ec_command - Information about a ChromeOS EC command.

 * @version: Command version number (often 0).

 * @command: Command to send (EC_CMD_...).

 * @outsize: Outgoing length in bytes.

 * @insize: Max number of bytes to accept from the EC.

 * @result: EC's response to the command (separate from communication failure).

 * @data: Where to put the incoming data from EC and outgoing data to EC.

 */

struct cros_ec_command {

	uint32_t version;
@@ -76,48 +77,55 @@ struct cros_ec_command { 
};



/**

 * struct cros_ec_device - Information about a ChromeOS EC device

 *

 * @phys_name: name of physical comms layer (e.g. 'i2c-4')

 * struct cros_ec_device - Information about a ChromeOS EC device.

 * @phys_name: Name of physical comms layer (e.g. 'i2c-4').

 * @dev: Device pointer for physical comms device

 * @was_wake_device: true if this device was set to wake the system from

 * sleep at the last suspend

 * @cmd_readmem: direct read of the EC memory-mapped region, if supported

 *     @offset is within EC_LPC_ADDR_MEMMAP region.

 *     @bytes: number of bytes to read. zero means "read a string" (including

 *     the trailing '\0'). At most only EC_MEMMAP_SIZE bytes can be read.

 *     Caller must ensure that the buffer is large enough for the result when

 *     reading a string.

 *

 * @priv: Private data

 * @irq: Interrupt to use

 * @id: Device id

 * @din: input buffer (for data from EC)

 * @dout: output buffer (for data to EC)

 * \note

 * These two buffers will always be dword-aligned and include enough

 * space for up to 7 word-alignment bytes also, so we can ensure that

 * the body of the message is always dword-aligned (64-bit).

 * We use this alignment to keep ARM and x86 happy. Probably word

 * alignment would be OK, there might be a small performance advantage

 * to using dword.

 * @din_size: size of din buffer to allocate (zero to use static din)

 * @dout_size: size of dout buffer to allocate (zero to use static dout)

 * @wake_enabled: true if this device can wake the system from sleep

 * @suspended: true if this device had been suspended

 * @cmd_xfer: send command to EC and get response

 *     Returns the number of bytes received if the communication succeeded, but

 *     that doesn't mean the EC was happy with the command. The caller

 *     should check msg.result for the EC's result code.

 * @pkt_xfer: send packet to EC and get response

 * @lock: one transaction at a time

 * @mkbp_event_supported: true if this EC supports the MKBP event protocol.

 * @event_notifier: interrupt event notifier for transport devices.

 * @event_data: raw payload transferred with the MKBP event.

 * @event_size: size in bytes of the event data.

 * @was_wake_device: True if this device was set to wake the system from

 *                   sleep at the last suspend.

 * @cros_class: The class structure for this device.

 * @cmd_readmem: Direct read of the EC memory-mapped region, if supported.

 *     @offset: Is within EC_LPC_ADDR_MEMMAP region.

 *     @bytes: Number of bytes to read. zero means "read a string" (including

 *             the trailing '\0'). At most only EC_MEMMAP_SIZE bytes can be

 *             read. Caller must ensure that the buffer is large enough for the

 *             result when reading a string.

 * @max_request: Max size of message requested.

 * @max_response: Max size of message response.

 * @max_passthru: Max sice of passthru message.

 * @proto_version: The protocol version used for this device.

 * @priv: Private data.

 * @irq: Interrupt to use.

 * @id: Device id.

 * @din: Input buffer (for data from EC). This buffer will always be

 *       dword-aligned and include enough space for up to 7 word-alignment

 *       bytes also, so we can ensure that the body of the message is always

 *       dword-aligned (64-bit). We use this alignment to keep ARM and x86

 *       happy. Probably word alignment would be OK, there might be a small

 *       performance advantage to using dword.

 * @dout: Output buffer (for data to EC). This buffer will always be

 *        dword-aligned and include enough space for up to 7 word-alignment

 *        bytes also, so we can ensure that the body of the message is always

 *        dword-aligned (64-bit). We use this alignment to keep ARM and x86

 *        happy. Probably word alignment would be OK, there might be a small

 *        performance advantage to using dword.

 * @din_size: Size of din buffer to allocate (zero to use static din).

 * @dout_size: Size of dout buffer to allocate (zero to use static dout).

 * @wake_enabled: True if this device can wake the system from sleep.

 * @suspended: True if this device had been suspended.

 * @cmd_xfer: Send command to EC and get response.

 *            Returns the number of bytes received if the communication

 *            succeeded, but that doesn't mean the EC was happy with the

 *            command. The caller should check msg.result for the EC's result

 *            code.

 * @pkt_xfer: Send packet to EC and get response.

 * @lock: One transaction at a time.

 * @mkbp_event_supported: True if this EC supports the MKBP event protocol.

 * @event_notifier: Interrupt event notifier for transport devices.

 * @event_data: Raw payload transferred with the MKBP event.

 * @event_size: Size in bytes of the event data.

 * @host_event_wake_mask: Mask of host events that cause wake from suspend.

 */

struct cros_ec_device {



	/* These are used by other drivers that want to talk to the EC */

	const char *phys_name;

	struct device *dev;
@@ -153,20 +161,19 @@ struct cros_ec_device { 
};



/**

 * struct cros_ec_sensor_platform - ChromeOS EC sensor platform information

 *

 * struct cros_ec_sensor_platform - ChromeOS EC sensor platform information.

 * @sensor_num: Id of the sensor, as reported by the EC.

 */

struct cros_ec_sensor_platform {

	u8 sensor_num;

};



/* struct cros_ec_platform - ChromeOS EC platform information

 *

 * @ec_name: name of EC device (e.g. 'cros-ec', 'cros-pd', ...)

/**

 * struct cros_ec_platform - ChromeOS EC platform information.

 * @ec_name: Name of EC device (e.g. 'cros-ec', 'cros-pd', ...)

 *           used in /dev/ and sysfs.

 * @cmd_offset: offset to apply for each command. Set when

 * registering a devicde behind another one.

 * @cmd_offset: Offset to apply for each command. Set when

 *              registering a device behind another one.

 */

struct cros_ec_platform {

	const char *ec_name;
@@ -175,16 +182,16 @@ struct cros_ec_platform { 


struct cros_ec_debugfs;



/*

 * struct cros_ec_dev - ChromeOS EC device entry point

 *

 * @class_dev: Device structure used in sysfs

 * @cdev: Character device structure in /dev

 * @ec_dev: cros_ec_device structure to talk to the physical device

 * @dev: pointer to the platform device

 * @debug_info: cros_ec_debugfs structure for debugging information

 * @has_kb_wake_angle: true if at least 2 accelerometer are connected to the EC.

 * @cmd_offset: offset to apply for each command.

/**

 * struct cros_ec_dev - ChromeOS EC device entry point.

 * @class_dev: Device structure used in sysfs.

 * @cdev: Character device structure in /dev.

 * @ec_dev: cros_ec_device structure to talk to the physical device.

 * @dev: Pointer to the platform device.

 * @debug_info: cros_ec_debugfs structure for debugging information.

 * @has_kb_wake_angle: True if at least 2 accelerometer are connected to the EC.

 * @cmd_offset: Offset to apply for each command.

 * @features: Features supported by the EC.

 */

struct cros_ec_dev {

	struct device class_dev;
@@ -200,124 +207,129 @@ struct cros_ec_dev { 
#define to_cros_ec_dev(dev)  container_of(dev, struct cros_ec_dev, class_dev)



/**

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

 * 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.

 *

 * ec_dev: Device to suspend

 * @return 0 if ok, -ve on error

 * 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

 * 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.

 *

 * @ec_dev: Device to resume

 * @return 0 if ok, -ve on error

 * 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

 * 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.

 *

 * @ec_dev: Device to register

 * @msg: Message to write

 * 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

 * 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.

 *

 * @ec_dev: EC device

 * @msg: Message to check

 * 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

 * 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.

 *

 * @ec_dev: EC device

 * @msg: Message to write

 * 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

 * 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.

 *

 * @ec_dev: EC device

 * @msg: Message to write

 * @return: Num. of bytes transferred on success, <0 on failure

 * 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_remove - Remove a ChromeOS EC

 * cros_ec_remove() - Remove a ChromeOS EC.

 * @ec_dev: Device to register.

 *

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

 *

 * @ec_dev: Device to register

 * @return 0 if ok, -ve on error

 * Return: 0 on success or negative error code.

 */

int cros_ec_remove(struct cros_ec_device *ec_dev);



/**

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

 * 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.

 *

 * @ec_dev: Device to register

 * @return 0 if ok, -ve on error

 * Return: 0 on success or negative error code.

 */

int cros_ec_register(struct cros_ec_device *ec_dev);



/**

 * cros_ec_query_all -  Query the protocol version supported by the ChromeOS EC

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

 *         ChromeOS EC.

 * @ec_dev: Device to register.

 *

 * @ec_dev: Device to register

 * @return 0 if ok, -ve on error

 * 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

 * 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.

 *

 * Returns: 0 on success, Linux error number on failure

 * Return: 0 on success or negative error code.

 */

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 EC.

 * 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.

 * 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.

 *

 * This function is a helper to know which events are raised.

 * Return: 0 on success or negative error code.

 */

u32 cros_ec_get_host_event(struct cros_ec_device *ec_dev);

include/linux/mfd/cros_ec_commands.h

+190 −105

File changed.

Preview size limit exceeded, changes collapsed.