include/linux/counter.h

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