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