xref: /openbmc/u-boot/include/misc.h (revision 6d9a98c5)
1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Copyright (C) 2015 Thomas Chou <thomas@wytron.com.tw>
4  */
5 
6 #ifndef _MISC_H_
7 #define _MISC_H_
8 
9 /**
10  * misc_read() - Read the device to buffer, optional.
11  * @dev: the device
12  * @offset: offset to read the device
13  * @buf: pointer to data buffer
14  * @size: data size in bytes to read the device
15  *
16  * Return: number of bytes read if OK (may be 0 if EOF), -ve on error
17  */
18 int misc_read(struct udevice *dev, int offset, void *buf, int size);
19 
20 /**
21  * misc_write() - Write buffer to the device, optional.
22  * @dev: the device
23  * @offset: offset to write the device
24  * @buf: pointer to data buffer
25  * @size: data size in bytes to write the device
26  *
27  * Return: number of bytes written if OK (may be < @size), -ve on error
28  */
29 int misc_write(struct udevice *dev, int offset, void *buf, int size);
30 
31 /**
32  * misc_ioctl() - Assert command to the device, optional.
33  * @dev: the device
34  * @request: command to be sent to the device
35  * @buf: pointer to buffer related to the request
36  *
37  * Return: 0 if OK, -ve on error
38  */
39 int misc_ioctl(struct udevice *dev, unsigned long request, void *buf);
40 
41 /**
42  * misc_call() - Send a message to the device and wait for a response.
43  * @dev: the device.
44  * @msgid: the message ID/number to send.
45  * @tx_msg: the request/transmit message payload.
46  * @tx_size: the size of the buffer pointed at by tx_msg.
47  * @rx_msg: the buffer to receive the response message payload. May be NULL if
48  *          the caller only cares about the error code.
49  * @rx_size: the size of the buffer pointed at by rx_msg.
50  *
51  * The caller provides the message type/ID and payload to be sent.
52  * The callee constructs any message header required, transmits it to the
53  * target, waits for a response, checks any error code in the response,
54  * strips any message header from the response, and returns the error code
55  * (or a parsed version of it) and the response message payload.
56  *
57  * Return: the response message size if OK, -ve on error
58  */
59 int misc_call(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
60 	      void *rx_msg, int rx_size);
61 
62 /**
63  * misc_set_enabled() - Enable or disable a device.
64  * @dev: the device to enable or disable.
65  * @val: the flag that tells the driver to either enable or disable the device.
66  *
67  * The semantics of "disable" and "enable" should be understood here as
68  * activating or deactivating the device's primary function, hence a "disabled"
69  * device should be dormant, but still answer to commands and queries.
70  *
71  * A probed device may start in a disabled or enabled state, depending on the
72  * driver and hardware.
73  *
74  * Return: -ve on error, 0 if the previous state was "disabled", 1 if the
75  *	   previous state was "enabled"
76  */
77 int misc_set_enabled(struct udevice *dev, bool val);
78 
79 /*
80  * struct misc_ops - Driver model Misc operations
81  *
82  * The uclass interface is implemented by all miscellaneous devices which
83  * use driver model.
84  */
85 struct misc_ops {
86 	/**
87 	 * Read the device to buffer, optional.
88 	 * @dev: the device
89 	 * @offset: offset to read the device
90 	 * @buf: pointer to data buffer
91 	 * @size: data size in bytes to read the device
92 	 *
93 	 * Return: number of bytes read if OK (may be 0 if EOF), -ve on error
94 	 */
95 	int (*read)(struct udevice *dev, int offset, void *buf, int size);
96 
97 	/**
98 	 * Write buffer to the device, optional.
99 	 * @dev: the device
100 	 * @offset: offset to write the device
101 	 * @buf: pointer to data buffer
102 	 * @size: data size in bytes to write the device
103 	 *
104 	 * Return: number of bytes written if OK (may be < @size), -ve on error
105 	 */
106 	int (*write)(struct udevice *dev, int offset, const void *buf,
107 		     int size);
108 	/**
109 	 * Assert command to the device, optional.
110 	 * @dev: the device
111 	 * @request: command to be sent to the device
112 	 * @buf: pointer to buffer related to the request
113 	 *
114 	 * Return: 0 if OK, -ve on error
115 	 */
116 	int (*ioctl)(struct udevice *dev, unsigned long request, void *buf);
117 
118 	/**
119 	 * Send a message to the device and wait for a response.
120 	 * @dev: the device
121 	 * @msgid: the message ID/number to send
122 	 * @tx_msg: the request/transmit message payload
123 	 * @tx_size: the size of the buffer pointed at by tx_msg
124 	 * @rx_msg: the buffer to receive the response message payload. May be
125 	 *          NULL if the caller only cares about the error code.
126 	 * @rx_size: the size of the buffer pointed at by rx_msg
127 	 *
128 	 * Return: the response message size if OK, -ve on error
129 	 */
130 	int (*call)(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
131 		    void *rx_msg, int rx_size);
132 	/**
133 	 * Enable or disable a device, optional.
134 	 * @dev: the device to enable.
135 	 * @val: the flag that tells the driver to either enable or disable the
136 	 *	 device.
137 	 *
138 	 * Return: -ve on error, 0 if the previous state was "disabled", 1 if
139 	 *	   the previous state was "enabled"
140 	 */
141 	int (*set_enabled)(struct udevice *dev, bool val);
142 };
143 
144 #endif	/* _MISC_H_ */
145