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_ */ 511
