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/cdev.h>
  10 #include <linux/device.h>
  11 #include <linux/kernel.h>
  12 #include <linux/kfifo.h>
  13 #include <linux/mutex.h>
  14 #include <linux/spinlock_types.h>
  15 #include <linux/types.h>
  16 #include <linux/wait.h>
  17 #include <uapi/linux/counter.h>
  18
  19 struct counter_device;
  20 struct counter_count;
  21 struct counter_synapse;
  22 struct counter_signal;
  23
  24 enum counter_comp_type {
  25         COUNTER_COMP_U8,
  26         COUNTER_COMP_U64,
  27         COUNTER_COMP_BOOL,
  28         COUNTER_COMP_SIGNAL_LEVEL,
  29         COUNTER_COMP_FUNCTION,
  30         COUNTER_COMP_SYNAPSE_ACTION,
  31         COUNTER_COMP_ENUM,
  32         COUNTER_COMP_COUNT_DIRECTION,
  33         COUNTER_COMP_COUNT_MODE,
  34 };
  35
  36 /**
  37  * struct counter_comp - Counter component node
  38  * @type:               Counter component data type
  39  * @name:               device-specific component name
  40  * @priv:               component-relevant data
  41  * @action_read:                Synapse action mode read callback. The read value of the
  42  *                      respective Synapse action mode should be passed back via
  43  *                      the action parameter.
  44  * @device_u8_read:             Device u8 component read callback. The read value of the
  45  *                      respective Device u8 component should be passed back via
  46  *                      the val parameter.
  47  * @count_u8_read:              Count u8 component read callback. The read value of the
  48  *                      respective Count u8 component should be passed back via
  49  *                      the val parameter.
  50  * @signal_u8_read:             Signal u8 component read callback. The read value of the
  51  *                      respective Signal u8 component should be passed back via
  52  *                      the val parameter.
  53  * @device_u32_read:            Device u32 component read callback. The read value of
  54  *                      the respective Device u32 component should be passed
  55  *                      back via the val parameter.
  56  * @count_u32_read:             Count u32 component read callback. The read value of the
  57  *                      respective Count u32 component should be passed back via
  58  *                      the val parameter.
  59  * @signal_u32_read:            Signal u32 component read callback. The read value of
  60  *                      the respective Signal u32 component should be passed
  61  *                      back via the val parameter.
  62  * @device_u64_read:            Device u64 component read callback. The read value of
  63  *                      the respective Device u64 component should be passed
  64  *                      back via the val parameter.
  65  * @count_u64_read:             Count u64 component read callback. The read value of the
  66  *                      respective Count u64 component should be passed back via
  67  *                      the val parameter.
  68  * @signal_u64_read:            Signal u64 component read callback. The read value of
  69  *                      the respective Signal u64 component should be passed
  70  *                      back via the val parameter.
  71  * @action_write:               Synapse action mode write callback. The write value of
  72  *                      the respective Synapse action mode is passed via the
  73  *                      action parameter.
  74  * @device_u8_write:            Device u8 component write callback. The write value of
  75  *                      the respective Device u8 component is passed via the val
  76  *                      parameter.
  77  * @count_u8_write:             Count u8 component write callback. The write value of
  78  *                      the respective Count u8 component is passed via the val
  79  *                      parameter.
  80  * @signal_u8_write:            Signal u8 component write callback. The write value of
  81  *                      the respective Signal u8 component is passed via the val
  82  *                      parameter.
  83  * @device_u32_write:           Device u32 component write callback. The write value of
  84  *                      the respective Device u32 component is passed via the
  85  *                      val parameter.
  86  * @count_u32_write:            Count u32 component write callback. The write value of
  87  *                      the respective Count u32 component is passed via the val
  88  *                      parameter.
  89  * @signal_u32_write:           Signal u32 component write callback. The write value of
  90  *                      the respective Signal u32 component is passed via the
  91  *                      val parameter.
  92  * @device_u64_write:           Device u64 component write callback. The write value of
  93  *                      the respective Device u64 component is passed via the
  94  *                      val parameter.
  95  * @count_u64_write:            Count u64 component write callback. The write value of
  96  *                      the respective Count u64 component is passed via the val
  97  *                      parameter.
  98  * @signal_u64_write:           Signal u64 component write callback. The write value of
  99  *                      the respective Signal u64 component is passed via the
 100  *                      val parameter.
 101  */
 102 struct counter_comp {
 103         enum counter_comp_type type;
 104         const char *name;
 105         void *priv;
 106         union {
 107                 int (*action_read)(struct counter_device *counter,
 108                                    struct counter_count *count,
 109                                    struct counter_synapse *synapse,
 110                                    enum counter_synapse_action *action);
 111                 int (*device_u8_read)(struct counter_device *counter, u8 *val);
 112                 int (*count_u8_read)(struct counter_device *counter,
 113                                      struct counter_count *count, u8 *val);
 114                 int (*signal_u8_read)(struct counter_device *counter,
 115                                       struct counter_signal *signal, u8 *val);
 116                 int (*device_u32_read)(struct counter_device *counter,
 117                                        u32 *val);
 118                 int (*count_u32_read)(struct counter_device *counter,
 119                                       struct counter_count *count, u32 *val);
 120                 int (*signal_u32_read)(struct counter_device *counter,
 121                                        struct counter_signal *signal, u32 *val);
 122                 int (*device_u64_read)(struct counter_device *counter,
 123                                        u64 *val);
 124                 int (*count_u64_read)(struct counter_device *counter,
 125                                       struct counter_count *count, u64 *val);
 126                 int (*signal_u64_read)(struct counter_device *counter,
 127                                        struct counter_signal *signal, u64 *val);
 128         };
 129         union {
 130                 int (*action_write)(struct counter_device *counter,
 131                                     struct counter_count *count,
 132                                     struct counter_synapse *synapse,
 133                                     enum counter_synapse_action action);
 134                 int (*device_u8_write)(struct counter_device *counter, u8 val);
 135                 int (*count_u8_write)(struct counter_device *counter,
 136                                       struct counter_count *count, u8 val);
 137                 int (*signal_u8_write)(struct counter_device *counter,
 138                                        struct counter_signal *signal, u8 val);
 139                 int (*device_u32_write)(struct counter_device *counter,
 140                                         u32 val);
 141                 int (*count_u32_write)(struct counter_device *counter,
 142                                        struct counter_count *count, u32 val);
 143                 int (*signal_u32_write)(struct counter_device *counter,
 144                                         struct counter_signal *signal, u32 val);
 145                 int (*device_u64_write)(struct counter_device *counter,
 146                                         u64 val);
 147                 int (*count_u64_write)(struct counter_device *counter,
 148                                        struct counter_count *count, u64 val);
 149                 int (*signal_u64_write)(struct counter_device *counter,
 150                                         struct counter_signal *signal, u64 val);
 151         };
 152 };
 153
 154 /**
 155  * struct counter_signal - Counter Signal node
 156  * @id:         unique ID used to identify the Signal
 157  * @name:       device-specific Signal name
 158  * @ext:        optional array of Signal extensions
 159  * @num_ext:    number of Signal extensions specified in @ext
 160  */
 161 struct counter_signal {
 162         int id;
 163         const char *name;
 164
 165         struct counter_comp *ext;
 166         size_t num_ext;
 167 };
 168
 169 /**
 170  * struct counter_synapse - Counter Synapse node
 171  * @actions_list:       array of available action modes
 172  * @num_actions:        number of action modes specified in @actions_list
 173  * @signal:             pointer to the associated Signal
 174  */
 175 struct counter_synapse {
 176         const enum counter_synapse_action *actions_list;
 177         size_t num_actions;
 178
 179         struct counter_signal *signal;
 180 };
 181
 182 /**
 183  * struct counter_count - Counter Count node
 184  * @id:                 unique ID used to identify the Count
 185  * @name:               device-specific Count name
 186  * @functions_list:     array of available function modes
 187  * @num_functions:      number of function modes specified in @functions_list
 188  * @synapses:           array of Synapses for initialization
 189  * @num_synapses:       number of Synapses specified in @synapses
 190  * @ext:                optional array of Count extensions
 191  * @num_ext:            number of Count extensions specified in @ext
 192  */
 193 struct counter_count {
 194         int id;
 195         const char *name;
 196
 197         const enum counter_function *functions_list;
 198         size_t num_functions;
 199
 200         struct counter_synapse *synapses;
 201         size_t num_synapses;
 202
 203         struct counter_comp *ext;
 204         size_t num_ext;
 205 };
 206
 207 /**
 208  * struct counter_event_node - Counter Event node
 209  * @l:          list of current watching Counter events
 210  * @event:      event that triggers
 211  * @channel:    event channel
 212  * @comp_list:  list of components to watch when event triggers
 213  */
 214 struct counter_event_node {
 215         struct list_head l;
 216         u8 event;
 217         u8 channel;
 218         struct list_head comp_list;
 219 };
 220
 221 /**
 222  * struct counter_ops - Callbacks from driver
 223  * @signal_read:        optional read callback for Signals. The read level of
 224  *                      the respective Signal should be passed back via the
 225  *                      level parameter.
 226  * @count_read:         read callback for Counts. The read value of the
 227  *                      respective Count should be passed back via the value
 228  *                      parameter.
 229  * @count_write:        optional write callback for Counts. The write value for
 230  *                      the respective Count is passed in via the value
 231  *                      parameter.
 232  * @function_read:      read callback the Count function modes. The read
 233  *                      function mode of the respective Count should be passed
 234  *                      back via the function parameter.
 235  * @function_write:     optional write callback for Count function modes. The
 236  *                      function mode to write for the respective Count is
 237  *                      passed in via the function parameter.
 238  * @action_read:        optional read callback the Synapse action modes. The
 239  *                      read action mode of the respective Synapse should be
 240  *                      passed back via the action parameter.
 241  * @action_write:       optional write callback for Synapse action modes. The
 242  *                      action mode to write for the respective Synapse is
 243  *                      passed in via the action parameter.
 244  * @events_configure:   optional write callback to configure events. The list of
 245  *                      struct counter_event_node may be accessed via the
 246  *                      events_list member of the counter parameter.
 247  * @watch_validate:     optional callback to validate a watch. The Counter
 248  *                      component watch configuration is passed in via the watch
 249  *                      parameter. A return value of 0 indicates a valid Counter
 250  *                      component watch configuration.
 251  */
 252 struct counter_ops {
 253         int (*signal_read)(struct counter_device *counter,
 254                            struct counter_signal *signal,
 255                            enum counter_signal_level *level);
 256         int (*count_read)(struct counter_device *counter,
 257                           struct counter_count *count, u64 *value);
 258         int (*count_write)(struct counter_device *counter,
 259                            struct counter_count *count, u64 value);
 260         int (*function_read)(struct counter_device *counter,
 261                              struct counter_count *count,
 262                              enum counter_function *function);
 263         int (*function_write)(struct counter_device *counter,
 264                               struct counter_count *count,
 265                               enum counter_function function);
 266         int (*action_read)(struct counter_device *counter,
 267                            struct counter_count *count,
 268                            struct counter_synapse *synapse,
 269                            enum counter_synapse_action *action);
 270         int (*action_write)(struct counter_device *counter,
 271                             struct counter_count *count,
 272                             struct counter_synapse *synapse,
 273                             enum counter_synapse_action action);
 274         int (*events_configure)(struct counter_device *counter);
 275         int (*watch_validate)(struct counter_device *counter,
 276                               const struct counter_watch *watch);
 277 };
 278
 279 /**
 280  * struct counter_device - Counter data structure
 281  * @name:               name of the device
 282  * @parent:             optional parent device providing the counters
 283  * @ops:                callbacks from driver
 284  * @signals:            array of Signals
 285  * @num_signals:        number of Signals specified in @signals
 286  * @counts:             array of Counts
 287  * @num_counts:         number of Counts specified in @counts
 288  * @ext:                optional array of Counter device extensions
 289  * @num_ext:            number of Counter device extensions specified in @ext
 290  * @priv:               optional private data supplied by driver
 291  * @dev:                internal device structure
 292  * @chrdev:             internal character device structure
 293  * @events_list:        list of current watching Counter events
 294  * @events_list_lock:   lock to protect Counter events list operations
 295  * @next_events_list:   list of next watching Counter events
 296  * @n_events_list_lock: lock to protect Counter next events list operations
 297  * @events:             queue of detected Counter events
 298  * @events_wait:        wait queue to allow blocking reads of Counter events
 299  * @events_in_lock:     lock to protect Counter events queue in operations
 300  * @events_out_lock:    lock to protect Counter events queue out operations
 301  * @ops_exist_lock:     lock to prevent use during removal
 302  */
 303 struct counter_device {
 304         const char *name;
 305         struct device *parent;
 306
 307         const struct counter_ops *ops;
 308
 309         struct counter_signal *signals;
 310         size_t num_signals;
 311         struct counter_count *counts;
 312         size_t num_counts;
 313
 314         struct counter_comp *ext;
 315         size_t num_ext;
 316
 317         struct device dev;
 318         struct cdev chrdev;
 319         struct list_head events_list;
 320         spinlock_t events_list_lock;
 321         struct list_head next_events_list;
 322         struct mutex n_events_list_lock;
 323         DECLARE_KFIFO_PTR(events, struct counter_event);
 324         wait_queue_head_t events_wait;
 325         spinlock_t events_in_lock;
 326         struct mutex events_out_lock;
 327         struct mutex ops_exist_lock;
 328 };
 329
 330 void *counter_priv(const struct counter_device *const counter);
 331
 332 struct counter_device *counter_alloc(size_t sizeof_priv);
 333 void counter_put(struct counter_device *const counter);
 334 int counter_add(struct counter_device *const counter);
 335
 336 void counter_unregister(struct counter_device *const counter);
 337 struct counter_device *devm_counter_alloc(struct device *dev,
 338                                           size_t sizeof_priv);
 339 int devm_counter_add(struct device *dev,
 340                      struct counter_device *const counter);
 341 void counter_push_event(struct counter_device *const counter, const u8 event,
 342                         const u8 channel);
 343
 344 #define COUNTER_COMP_DEVICE_U8(_name, _read, _write) \
 345 { \
 346         .type = COUNTER_COMP_U8, \
 347         .name = (_name), \
 348         .device_u8_read = (_read), \
 349         .device_u8_write = (_write), \
 350 }
 351 #define COUNTER_COMP_COUNT_U8(_name, _read, _write) \
 352 { \
 353         .type = COUNTER_COMP_U8, \
 354         .name = (_name), \
 355         .count_u8_read = (_read), \
 356         .count_u8_write = (_write), \
 357 }
 358 #define COUNTER_COMP_SIGNAL_U8(_name, _read, _write) \
 359 { \
 360         .type = COUNTER_COMP_U8, \
 361         .name = (_name), \
 362         .signal_u8_read = (_read), \
 363         .signal_u8_write = (_write), \
 364 }
 365
 366 #define COUNTER_COMP_DEVICE_U64(_name, _read, _write) \
 367 { \
 368         .type = COUNTER_COMP_U64, \
 369         .name = (_name), \
 370         .device_u64_read = (_read), \
 371         .device_u64_write = (_write), \
 372 }
 373 #define COUNTER_COMP_COUNT_U64(_name, _read, _write) \
 374 { \
 375         .type = COUNTER_COMP_U64, \
 376         .name = (_name), \
 377         .count_u64_read = (_read), \
 378         .count_u64_write = (_write), \
 379 }
 380 #define COUNTER_COMP_SIGNAL_U64(_name, _read, _write) \
 381 { \
 382         .type = COUNTER_COMP_U64, \
 383         .name = (_name), \
 384         .signal_u64_read = (_read), \
 385         .signal_u64_write = (_write), \
 386 }
 387
 388 #define COUNTER_COMP_DEVICE_BOOL(_name, _read, _write) \
 389 { \
 390         .type = COUNTER_COMP_BOOL, \
 391         .name = (_name), \
 392         .device_u8_read = (_read), \
 393         .device_u8_write = (_write), \
 394 }
 395 #define COUNTER_COMP_COUNT_BOOL(_name, _read, _write) \
 396 { \
 397         .type = COUNTER_COMP_BOOL, \
 398         .name = (_name), \
 399         .count_u8_read = (_read), \
 400         .count_u8_write = (_write), \
 401 }
 402 #define COUNTER_COMP_SIGNAL_BOOL(_name, _read, _write) \
 403 { \
 404         .type = COUNTER_COMP_BOOL, \
 405         .name = (_name), \
 406         .signal_u8_read = (_read), \
 407         .signal_u8_write = (_write), \
 408 }
 409
 410 struct counter_available {
 411         union {
 412                 const u32 *enums;
 413                 const char *const *strs;
 414         };
 415         size_t num_items;
 416 };
 417
 418 #define DEFINE_COUNTER_AVAILABLE(_name, _enums) \
 419         struct counter_available _name = { \
 420                 .enums = (_enums), \
 421                 .num_items = ARRAY_SIZE(_enums), \
 422         }
 423
 424 #define DEFINE_COUNTER_ENUM(_name, _strs) \
 425         struct counter_available _name = { \
 426                 .strs = (_strs), \
 427                 .num_items = ARRAY_SIZE(_strs), \
 428         }
 429
 430 #define COUNTER_COMP_DEVICE_ENUM(_name, _get, _set, _available) \
 431 { \
 432         .type = COUNTER_COMP_ENUM, \
 433         .name = (_name), \
 434         .device_u32_read = (_get), \
 435         .device_u32_write = (_set), \
 436         .priv = &(_available), \
 437 }
 438 #define COUNTER_COMP_COUNT_ENUM(_name, _get, _set, _available) \
 439 { \
 440         .type = COUNTER_COMP_ENUM, \
 441         .name = (_name), \
 442         .count_u32_read = (_get), \
 443         .count_u32_write = (_set), \
 444         .priv = &(_available), \
 445 }
 446 #define COUNTER_COMP_SIGNAL_ENUM(_name, _get, _set, _available) \
 447 { \
 448         .type = COUNTER_COMP_ENUM, \
 449         .name = (_name), \
 450         .signal_u32_read = (_get), \
 451         .signal_u32_write = (_set), \
 452         .priv = &(_available), \
 453 }
 454
 455 #define COUNTER_COMP_CEILING(_read, _write) \
 456         COUNTER_COMP_COUNT_U64("ceiling", _read, _write)
 457
 458 #define COUNTER_COMP_COUNT_MODE(_read, _write, _available) \
 459 { \
 460         .type = COUNTER_COMP_COUNT_MODE, \
 461         .name = "count_mode", \
 462         .count_u32_read = (_read), \
 463         .count_u32_write = (_write), \
 464         .priv = &(_available), \
 465 }
 466
 467 #define COUNTER_COMP_DIRECTION(_read) \
 468 { \
 469         .type = COUNTER_COMP_COUNT_DIRECTION, \
 470         .name = "direction", \
 471         .count_u32_read = (_read), \
 472 }
 473
 474 #define COUNTER_COMP_ENABLE(_read, _write) \
 475         COUNTER_COMP_COUNT_BOOL("enable", _read, _write)
 476
 477 #define COUNTER_COMP_FLOOR(_read, _write) \
 478         COUNTER_COMP_COUNT_U64("floor", _read, _write)
 479
 480 #define COUNTER_COMP_PRESET(_read, _write) \
 481         COUNTER_COMP_COUNT_U64("preset", _read, _write)
 482
 483 #define COUNTER_COMP_PRESET_ENABLE(_read, _write) \
 484         COUNTER_COMP_COUNT_BOOL("preset_enable", _read, _write)
 485
 486 #endif /* _COUNTER_H_ */