counter.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Counter interface
  4. * Copyright (C) 2018 William Breathitt Gray
  5. */
  6. #ifndef _COUNTER_H_
  7. #define _COUNTER_H_
  8. #include <linux/counter_enum.h>
  9. #include <linux/device.h>
  10. #include <linux/types.h>
  11. enum counter_count_direction {
  12. COUNTER_COUNT_DIRECTION_FORWARD = 0,
  13. COUNTER_COUNT_DIRECTION_BACKWARD
  14. };
  15. extern const char *const counter_count_direction_str[2];
  16. enum counter_count_mode {
  17. COUNTER_COUNT_MODE_NORMAL = 0,
  18. COUNTER_COUNT_MODE_RANGE_LIMIT,
  19. COUNTER_COUNT_MODE_NON_RECYCLE,
  20. COUNTER_COUNT_MODE_MODULO_N
  21. };
  22. extern const char *const counter_count_mode_str[4];
  23. struct counter_device;
  24. struct counter_signal;
  25. /**
  26. * struct counter_signal_ext - Counter Signal extensions
  27. * @name: attribute name
  28. * @read: read callback for this attribute; may be NULL
  29. * @write: write callback for this attribute; may be NULL
  30. * @priv: data private to the driver
  31. */
  32. struct counter_signal_ext {
  33. const char *name;
  34. ssize_t (*read)(struct counter_device *counter,
  35. struct counter_signal *signal, void *priv, char *buf);
  36. ssize_t (*write)(struct counter_device *counter,
  37. struct counter_signal *signal, void *priv,
  38. const char *buf, size_t len);
  39. void *priv;
  40. };
  41. /**
  42. * struct counter_signal - Counter Signal node
  43. * @id: unique ID used to identify signal
  44. * @name: device-specific Signal name; ideally, this should match the name
  45. * as it appears in the datasheet documentation
  46. * @ext: optional array of Counter Signal extensions
  47. * @num_ext: number of Counter Signal extensions specified in @ext
  48. * @priv: optional private data supplied by driver
  49. */
  50. struct counter_signal {
  51. int id;
  52. const char *name;
  53. const struct counter_signal_ext *ext;
  54. size_t num_ext;
  55. void *priv;
  56. };
  57. /**
  58. * struct counter_signal_enum_ext - Signal enum extension attribute
  59. * @items: Array of strings
  60. * @num_items: Number of items specified in @items
  61. * @set: Set callback function; may be NULL
  62. * @get: Get callback function; may be NULL
  63. *
  64. * The counter_signal_enum_ext structure can be used to implement enum style
  65. * Signal extension attributes. Enum style attributes are those which have a set
  66. * of strings that map to unsigned integer values. The Generic Counter Signal
  67. * enum extension helper code takes care of mapping between value and string, as
  68. * well as generating a "_available" file which contains a list of all available
  69. * items. The get callback is used to query the currently active item; the index
  70. * of the item within the respective items array is returned via the 'item'
  71. * parameter. The set callback is called when the attribute is updated; the
  72. * 'item' parameter contains the index of the newly activated item within the
  73. * respective items array.
  74. */
  75. struct counter_signal_enum_ext {
  76. const char * const *items;
  77. size_t num_items;
  78. int (*get)(struct counter_device *counter,
  79. struct counter_signal *signal, size_t *item);
  80. int (*set)(struct counter_device *counter,
  81. struct counter_signal *signal, size_t item);
  82. };
  83. /**
  84. * COUNTER_SIGNAL_ENUM() - Initialize Signal enum extension
  85. * @_name: Attribute name
  86. * @_e: Pointer to a counter_signal_enum_ext structure
  87. *
  88. * This should usually be used together with COUNTER_SIGNAL_ENUM_AVAILABLE()
  89. */
  90. #define COUNTER_SIGNAL_ENUM(_name, _e) \
  91. { \
  92. .name = (_name), \
  93. .read = counter_signal_enum_read, \
  94. .write = counter_signal_enum_write, \
  95. .priv = (_e) \
  96. }
  97. /**
  98. * COUNTER_SIGNAL_ENUM_AVAILABLE() - Initialize Signal enum available extension
  99. * @_name: Attribute name ("_available" will be appended to the name)
  100. * @_e: Pointer to a counter_signal_enum_ext structure
  101. *
  102. * Creates a read only attribute that lists all the available enum items in a
  103. * newline separated list. This should usually be used together with
  104. * COUNTER_SIGNAL_ENUM()
  105. */
  106. #define COUNTER_SIGNAL_ENUM_AVAILABLE(_name, _e) \
  107. { \
  108. .name = (_name "_available"), \
  109. .read = counter_signal_enum_available_read, \
  110. .priv = (_e) \
  111. }
  112. enum counter_synapse_action {
  113. COUNTER_SYNAPSE_ACTION_NONE = 0,
  114. COUNTER_SYNAPSE_ACTION_RISING_EDGE,
  115. COUNTER_SYNAPSE_ACTION_FALLING_EDGE,
  116. COUNTER_SYNAPSE_ACTION_BOTH_EDGES
  117. };
  118. /**
  119. * struct counter_synapse - Counter Synapse node
  120. * @action: index of current action mode
  121. * @actions_list: array of available action modes
  122. * @num_actions: number of action modes specified in @actions_list
  123. * @signal: pointer to associated signal
  124. */
  125. struct counter_synapse {
  126. size_t action;
  127. const enum counter_synapse_action *actions_list;
  128. size_t num_actions;
  129. struct counter_signal *signal;
  130. };
  131. struct counter_count;
  132. /**
  133. * struct counter_count_ext - Counter Count extension
  134. * @name: attribute name
  135. * @read: read callback for this attribute; may be NULL
  136. * @write: write callback for this attribute; may be NULL
  137. * @priv: data private to the driver
  138. */
  139. struct counter_count_ext {
  140. const char *name;
  141. ssize_t (*read)(struct counter_device *counter,
  142. struct counter_count *count, void *priv, char *buf);
  143. ssize_t (*write)(struct counter_device *counter,
  144. struct counter_count *count, void *priv,
  145. const char *buf, size_t len);
  146. void *priv;
  147. };
  148. enum counter_count_function {
  149. COUNTER_COUNT_FUNCTION_INCREASE = 0,
  150. COUNTER_COUNT_FUNCTION_DECREASE,
  151. COUNTER_COUNT_FUNCTION_PULSE_DIRECTION,
  152. COUNTER_COUNT_FUNCTION_QUADRATURE_X1_A,
  153. COUNTER_COUNT_FUNCTION_QUADRATURE_X1_B,
  154. COUNTER_COUNT_FUNCTION_QUADRATURE_X2_A,
  155. COUNTER_COUNT_FUNCTION_QUADRATURE_X2_B,
  156. COUNTER_COUNT_FUNCTION_QUADRATURE_X4
  157. };
  158. /**
  159. * struct counter_count - Counter Count node
  160. * @id: unique ID used to identify Count
  161. * @name: device-specific Count name; ideally, this should match
  162. * the name as it appears in the datasheet documentation
  163. * @function: index of current function mode
  164. * @functions_list: array available function modes
  165. * @num_functions: number of function modes specified in @functions_list
  166. * @synapses: array of synapses for initialization
  167. * @num_synapses: number of synapses specified in @synapses
  168. * @ext: optional array of Counter Count extensions
  169. * @num_ext: number of Counter Count extensions specified in @ext
  170. * @priv: optional private data supplied by driver
  171. */
  172. struct counter_count {
  173. int id;
  174. const char *name;
  175. size_t function;
  176. const enum counter_count_function *functions_list;
  177. size_t num_functions;
  178. struct counter_synapse *synapses;
  179. size_t num_synapses;
  180. const struct counter_count_ext *ext;
  181. size_t num_ext;
  182. void *priv;
  183. };
  184. /**
  185. * struct counter_count_enum_ext - Count enum extension attribute
  186. * @items: Array of strings
  187. * @num_items: Number of items specified in @items
  188. * @set: Set callback function; may be NULL
  189. * @get: Get callback function; may be NULL
  190. *
  191. * The counter_count_enum_ext structure can be used to implement enum style
  192. * Count extension attributes. Enum style attributes are those which have a set
  193. * of strings that map to unsigned integer values. The Generic Counter Count
  194. * enum extension helper code takes care of mapping between value and string, as
  195. * well as generating a "_available" file which contains a list of all available
  196. * items. The get callback is used to query the currently active item; the index
  197. * of the item within the respective items array is returned via the 'item'
  198. * parameter. The set callback is called when the attribute is updated; the
  199. * 'item' parameter contains the index of the newly activated item within the
  200. * respective items array.
  201. */
  202. struct counter_count_enum_ext {
  203. const char * const *items;
  204. size_t num_items;
  205. int (*get)(struct counter_device *counter, struct counter_count *count,
  206. size_t *item);
  207. int (*set)(struct counter_device *counter, struct counter_count *count,
  208. size_t item);
  209. };
  210. /**
  211. * COUNTER_COUNT_ENUM() - Initialize Count enum extension
  212. * @_name: Attribute name
  213. * @_e: Pointer to a counter_count_enum_ext structure
  214. *
  215. * This should usually be used together with COUNTER_COUNT_ENUM_AVAILABLE()
  216. */
  217. #define COUNTER_COUNT_ENUM(_name, _e) \
  218. { \
  219. .name = (_name), \
  220. .read = counter_count_enum_read, \
  221. .write = counter_count_enum_write, \
  222. .priv = (_e) \
  223. }
  224. /**
  225. * COUNTER_COUNT_ENUM_AVAILABLE() - Initialize Count enum available extension
  226. * @_name: Attribute name ("_available" will be appended to the name)
  227. * @_e: Pointer to a counter_count_enum_ext structure
  228. *
  229. * Creates a read only attribute that lists all the available enum items in a
  230. * newline separated list. This should usually be used together with
  231. * COUNTER_COUNT_ENUM()
  232. */
  233. #define COUNTER_COUNT_ENUM_AVAILABLE(_name, _e) \
  234. { \
  235. .name = (_name "_available"), \
  236. .read = counter_count_enum_available_read, \
  237. .priv = (_e) \
  238. }
  239. /**
  240. * struct counter_device_attr_group - internal container for attribute group
  241. * @attr_group: Counter sysfs attributes group
  242. * @attr_list: list to keep track of created Counter sysfs attributes
  243. * @num_attr: number of Counter sysfs attributes
  244. */
  245. struct counter_device_attr_group {
  246. struct attribute_group attr_group;
  247. struct list_head attr_list;
  248. size_t num_attr;
  249. };
  250. /**
  251. * struct counter_device_state - internal state container for a Counter device
  252. * @id: unique ID used to identify the Counter
  253. * @dev: internal device structure
  254. * @groups_list: attribute groups list (for Signals, Counts, and ext)
  255. * @num_groups: number of attribute groups containers
  256. * @groups: Counter sysfs attribute groups (to populate @dev.groups)
  257. */
  258. struct counter_device_state {
  259. int id;
  260. struct device dev;
  261. struct counter_device_attr_group *groups_list;
  262. size_t num_groups;
  263. const struct attribute_group **groups;
  264. };
  265. enum counter_signal_value {
  266. COUNTER_SIGNAL_LOW = 0,
  267. COUNTER_SIGNAL_HIGH
  268. };
  269. /**
  270. * struct counter_ops - Callbacks from driver
  271. * @signal_read: optional read callback for Signal attribute. The read
  272. * value of the respective Signal should be passed back via
  273. * the val parameter.
  274. * @count_read: optional read callback for Count attribute. The read
  275. * value of the respective Count should be passed back via
  276. * the val parameter.
  277. * @count_write: optional write callback for Count attribute. The write
  278. * value for the respective Count is passed in via the val
  279. * parameter.
  280. * @function_get: function to get the current count function mode. Returns
  281. * 0 on success and negative error code on error. The index
  282. * of the respective Count's returned function mode should
  283. * be passed back via the function parameter.
  284. * @function_set: function to set the count function mode. function is the
  285. * index of the requested function mode from the respective
  286. * Count's functions_list array.
  287. * @action_get: function to get the current action mode. Returns 0 on
  288. * success and negative error code on error. The index of
  289. * the respective Synapse's returned action mode should be
  290. * passed back via the action parameter.
  291. * @action_set: function to set the action mode. action is the index of
  292. * the requested action mode from the respective Synapse's
  293. * actions_list array.
  294. */
  295. struct counter_ops {
  296. int (*signal_read)(struct counter_device *counter,
  297. struct counter_signal *signal,
  298. enum counter_signal_value *val);
  299. int (*count_read)(struct counter_device *counter,
  300. struct counter_count *count, unsigned long *val);
  301. int (*count_write)(struct counter_device *counter,
  302. struct counter_count *count, unsigned long val);
  303. int (*function_get)(struct counter_device *counter,
  304. struct counter_count *count, size_t *function);
  305. int (*function_set)(struct counter_device *counter,
  306. struct counter_count *count, size_t function);
  307. int (*action_get)(struct counter_device *counter,
  308. struct counter_count *count,
  309. struct counter_synapse *synapse, size_t *action);
  310. int (*action_set)(struct counter_device *counter,
  311. struct counter_count *count,
  312. struct counter_synapse *synapse, size_t action);
  313. };
  314. /**
  315. * struct counter_device_ext - Counter device extension
  316. * @name: attribute name
  317. * @read: read callback for this attribute; may be NULL
  318. * @write: write callback for this attribute; may be NULL
  319. * @priv: data private to the driver
  320. */
  321. struct counter_device_ext {
  322. const char *name;
  323. ssize_t (*read)(struct counter_device *counter, void *priv, char *buf);
  324. ssize_t (*write)(struct counter_device *counter, void *priv,
  325. const char *buf, size_t len);
  326. void *priv;
  327. };
  328. /**
  329. * struct counter_device_enum_ext - Counter enum extension attribute
  330. * @items: Array of strings
  331. * @num_items: Number of items specified in @items
  332. * @set: Set callback function; may be NULL
  333. * @get: Get callback function; may be NULL
  334. *
  335. * The counter_device_enum_ext structure can be used to implement enum style
  336. * Counter extension attributes. Enum style attributes are those which have a
  337. * set of strings that map to unsigned integer values. The Generic Counter enum
  338. * extension helper code takes care of mapping between value and string, as well
  339. * as generating a "_available" file which contains a list of all available
  340. * items. The get callback is used to query the currently active item; the index
  341. * of the item within the respective items array is returned via the 'item'
  342. * parameter. The set callback is called when the attribute is updated; the
  343. * 'item' parameter contains the index of the newly activated item within the
  344. * respective items array.
  345. */
  346. struct counter_device_enum_ext {
  347. const char * const *items;
  348. size_t num_items;
  349. int (*get)(struct counter_device *counter, size_t *item);
  350. int (*set)(struct counter_device *counter, size_t item);
  351. };
  352. /**
  353. * COUNTER_DEVICE_ENUM() - Initialize Counter enum extension
  354. * @_name: Attribute name
  355. * @_e: Pointer to a counter_device_enum_ext structure
  356. *
  357. * This should usually be used together with COUNTER_DEVICE_ENUM_AVAILABLE()
  358. */
  359. #define COUNTER_DEVICE_ENUM(_name, _e) \
  360. { \
  361. .name = (_name), \
  362. .read = counter_device_enum_read, \
  363. .write = counter_device_enum_write, \
  364. .priv = (_e) \
  365. }
  366. /**
  367. * COUNTER_DEVICE_ENUM_AVAILABLE() - Initialize Counter enum available extension
  368. * @_name: Attribute name ("_available" will be appended to the name)
  369. * @_e: Pointer to a counter_device_enum_ext structure
  370. *
  371. * Creates a read only attribute that lists all the available enum items in a
  372. * newline separated list. This should usually be used together with
  373. * COUNTER_DEVICE_ENUM()
  374. */
  375. #define COUNTER_DEVICE_ENUM_AVAILABLE(_name, _e) \
  376. { \
  377. .name = (_name "_available"), \
  378. .read = counter_device_enum_available_read, \
  379. .priv = (_e) \
  380. }
  381. /**
  382. * struct counter_device - Counter data structure
  383. * @name: name of the device as it appears in the datasheet
  384. * @parent: optional parent device providing the counters
  385. * @device_state: internal device state container
  386. * @ops: callbacks from driver
  387. * @signals: array of Signals
  388. * @num_signals: number of Signals specified in @signals
  389. * @counts: array of Counts
  390. * @num_counts: number of Counts specified in @counts
  391. * @ext: optional array of Counter device extensions
  392. * @num_ext: number of Counter device extensions specified in @ext
  393. * @priv: optional private data supplied by driver
  394. */
  395. struct counter_device {
  396. const char *name;
  397. struct device *parent;
  398. struct counter_device_state *device_state;
  399. const struct counter_ops *ops;
  400. struct counter_signal *signals;
  401. size_t num_signals;
  402. struct counter_count *counts;
  403. size_t num_counts;
  404. const struct counter_device_ext *ext;
  405. size_t num_ext;
  406. void *priv;
  407. };
  408. int counter_register(struct counter_device *const counter);
  409. void counter_unregister(struct counter_device *const counter);
  410. int devm_counter_register(struct device *dev,
  411. struct counter_device *const counter);
  412. void devm_counter_unregister(struct device *dev,
  413. struct counter_device *const counter);
  414. #endif /* _COUNTER_H_ */