drivers/mux/core.c

   1 // SPDX-License-Identifier: GPL-2.0
   2 /*
   3  * Multiplexer subsystem
   4  *
   5  * Copyright (C) 2017 Axentia Technologies AB
   6  *
   7  * Author: Peter Rosin <peda@axentia.se>
   8  */
   9
  10 #define pr_fmt(fmt) "mux-core: " fmt
  11
  12 #include <linux/delay.h>
  13 #include <linux/device.h>
  14 #include <linux/err.h>
  15 #include <linux/export.h>
  16 #include <linux/idr.h>
  17 #include <linux/init.h>
  18 #include <linux/module.h>
  19 #include <linux/mux/consumer.h>
  20 #include <linux/mux/driver.h>
  21 #include <linux/of.h>
  22 #include <linux/of_platform.h>
  23 #include <linux/slab.h>
  24
  25 /*
  26  * The idle-as-is "state" is not an actual state that may be selected, it
  27  * only implies that the state should not be changed. So, use that state
  28  * as indication that the cached state of the multiplexer is unknown.
  29  */
  30 #define MUX_CACHE_UNKNOWN MUX_IDLE_AS_IS
  31
  32 static struct class mux_class = {
  33         .name = "mux",
  34         .owner = THIS_MODULE,
  35 };
  36
  37 static DEFINE_IDA(mux_ida);
  38
  39 static int __init mux_init(void)
  40 {
  41         ida_init(&mux_ida);
  42         return class_register(&mux_class);
  43 }
  44
  45 static void __exit mux_exit(void)
  46 {
  47         class_unregister(&mux_class);
  48         ida_destroy(&mux_ida);
  49 }
  50
  51 static void mux_chip_release(struct device *dev)
  52 {
  53         struct mux_chip *mux_chip = to_mux_chip(dev);
  54
  55         ida_simple_remove(&mux_ida, mux_chip->id);
  56         kfree(mux_chip);
  57 }
  58
  59 static const struct device_type mux_type = {
  60         .name = "mux-chip",
  61         .release = mux_chip_release,
  62 };
  63
  64 /**
  65  * mux_chip_alloc() - Allocate a mux-chip.
  66  * @dev: The parent device implementing the mux interface.
  67  * @controllers: The number of mux controllers to allocate for this chip.
  68  * @sizeof_priv: Size of extra memory area for private use by the caller.
  69  *
  70  * After allocating the mux-chip with the desired number of mux controllers
  71  * but before registering the chip, the mux driver is required to configure
  72  * the number of valid mux states in the mux_chip->mux[N].states members and
  73  * the desired idle state in the returned mux_chip->mux[N].idle_state members.
  74  * The default idle state is MUX_IDLE_AS_IS. The mux driver also needs to
  75  * provide a pointer to the operations struct in the mux_chip->ops member
  76  * before registering the mux-chip with mux_chip_register.
  77  *
  78  * Return: A pointer to the new mux-chip, or an ERR_PTR with a negative errno.
  79  */
  80 struct mux_chip *mux_chip_alloc(struct device *dev,
  81                                 unsigned int controllers, size_t sizeof_priv)
  82 {
  83         struct mux_chip *mux_chip;
  84         int i;
  85
  86         if (WARN_ON(!dev || !controllers))
  87                 return ERR_PTR(-EINVAL);
  88
  89         mux_chip = kzalloc(sizeof(*mux_chip) +
  90                            controllers * sizeof(*mux_chip->mux) +
  91                            sizeof_priv, GFP_KERNEL);
  92         if (!mux_chip)
  93                 return ERR_PTR(-ENOMEM);
  94
  95         mux_chip->mux = (struct mux_control *)(mux_chip + 1);
  96         mux_chip->dev.class = &mux_class;
  97         mux_chip->dev.type = &mux_type;
  98         mux_chip->dev.parent = dev;
  99         mux_chip->dev.of_node = dev->of_node;
 100         dev_set_drvdata(&mux_chip->dev, mux_chip);
 101
 102         mux_chip->id = ida_simple_get(&mux_ida, 0, 0, GFP_KERNEL);
 103         if (mux_chip->id < 0) {
 104                 int err = mux_chip->id;
 105
 106                 pr_err("muxchipX failed to get a device id\n");
 107                 kfree(mux_chip);
 108                 return ERR_PTR(err);
 109         }
 110         dev_set_name(&mux_chip->dev, "muxchip%d", mux_chip->id);
 111
 112         mux_chip->controllers = controllers;
 113         for (i = 0; i < controllers; ++i) {
 114                 struct mux_control *mux = &mux_chip->mux[i];
 115
 116                 mux->chip = mux_chip;
 117                 sema_init(&mux->lock, 1);
 118                 mux->cached_state = MUX_CACHE_UNKNOWN;
 119                 mux->idle_state = MUX_IDLE_AS_IS;
 120                 mux->last_change = ktime_get();
 121         }
 122
 123         device_initialize(&mux_chip->dev);
 124
 125         return mux_chip;
 126 }
 127 EXPORT_SYMBOL_GPL(mux_chip_alloc);
 128
 129 static int mux_control_set(struct mux_control *mux, int state)
 130 {
 131         int ret = mux->chip->ops->set(mux, state);
 132
 133         mux->cached_state = ret < 0 ? MUX_CACHE_UNKNOWN : state;
 134         if (ret >= 0)
 135                 mux->last_change = ktime_get();
 136
 137         return ret;
 138 }
 139
 140 /**
 141  * mux_chip_register() - Register a mux-chip, thus readying the controllers
 142  *                       for use.
 143  * @mux_chip: The mux-chip to register.
 144  *
 145  * Do not retry registration of the same mux-chip on failure. You should
 146  * instead put it away with mux_chip_free() and allocate a new one, if you
 147  * for some reason would like to retry registration.
 148  *
 149  * Return: Zero on success or a negative errno on error.
 150  */
 151 int mux_chip_register(struct mux_chip *mux_chip)
 152 {
 153         int i;
 154         int ret;
 155
 156         for (i = 0; i < mux_chip->controllers; ++i) {
 157                 struct mux_control *mux = &mux_chip->mux[i];
 158
 159                 if (mux->idle_state == mux->cached_state)
 160                         continue;
 161
 162                 ret = mux_control_set(mux, mux->idle_state);
 163                 if (ret < 0) {
 164                         dev_err(&mux_chip->dev, "unable to set idle state\n");
 165                         return ret;
 166                 }
 167         }
 168
 169         ret = device_add(&mux_chip->dev);
 170         if (ret < 0)
 171                 dev_err(&mux_chip->dev,
 172                         "device_add failed in %s: %d\n", __func__, ret);
 173         return ret;
 174 }
 175 EXPORT_SYMBOL_GPL(mux_chip_register);
 176
 177 /**
 178  * mux_chip_unregister() - Take the mux-chip off-line.
 179  * @mux_chip: The mux-chip to unregister.
 180  *
 181  * mux_chip_unregister() reverses the effects of mux_chip_register().
 182  * But not completely, you should not try to call mux_chip_register()
 183  * on a mux-chip that has been registered before.
 184  */
 185 void mux_chip_unregister(struct mux_chip *mux_chip)
 186 {
 187         device_del(&mux_chip->dev);
 188 }
 189 EXPORT_SYMBOL_GPL(mux_chip_unregister);
 190
 191 /**
 192  * mux_chip_free() - Free the mux-chip for good.
 193  * @mux_chip: The mux-chip to free.
 194  *
 195  * mux_chip_free() reverses the effects of mux_chip_alloc().
 196  */
 197 void mux_chip_free(struct mux_chip *mux_chip)
 198 {
 199         if (!mux_chip)
 200                 return;
 201
 202         put_device(&mux_chip->dev);
 203 }
 204 EXPORT_SYMBOL_GPL(mux_chip_free);
 205
 206 static void devm_mux_chip_release(struct device *dev, void *res)
 207 {
 208         struct mux_chip *mux_chip = *(struct mux_chip **)res;
 209
 210         mux_chip_free(mux_chip);
 211 }
 212
 213 /**
 214  * devm_mux_chip_alloc() - Resource-managed version of mux_chip_alloc().
 215  * @dev: The parent device implementing the mux interface.
 216  * @controllers: The number of mux controllers to allocate for this chip.
 217  * @sizeof_priv: Size of extra memory area for private use by the caller.
 218  *
 219  * See mux_chip_alloc() for more details.
 220  *
 221  * Return: A pointer to the new mux-chip, or an ERR_PTR with a negative errno.
 222  */
 223 struct mux_chip *devm_mux_chip_alloc(struct device *dev,
 224                                      unsigned int controllers,
 225                                      size_t sizeof_priv)
 226 {
 227         struct mux_chip **ptr, *mux_chip;
 228
 229         ptr = devres_alloc(devm_mux_chip_release, sizeof(*ptr), GFP_KERNEL);
 230         if (!ptr)
 231                 return ERR_PTR(-ENOMEM);
 232
 233         mux_chip = mux_chip_alloc(dev, controllers, sizeof_priv);
 234         if (IS_ERR(mux_chip)) {
 235                 devres_free(ptr);
 236                 return mux_chip;
 237         }
 238
 239         *ptr = mux_chip;
 240         devres_add(dev, ptr);
 241
 242         return mux_chip;
 243 }
 244 EXPORT_SYMBOL_GPL(devm_mux_chip_alloc);
 245
 246 static void devm_mux_chip_reg_release(struct device *dev, void *res)
 247 {
 248         struct mux_chip *mux_chip = *(struct mux_chip **)res;
 249
 250         mux_chip_unregister(mux_chip);
 251 }
 252
 253 /**
 254  * devm_mux_chip_register() - Resource-managed version mux_chip_register().
 255  * @dev: The parent device implementing the mux interface.
 256  * @mux_chip: The mux-chip to register.
 257  *
 258  * See mux_chip_register() for more details.
 259  *
 260  * Return: Zero on success or a negative errno on error.
 261  */
 262 int devm_mux_chip_register(struct device *dev,
 263                            struct mux_chip *mux_chip)
 264 {
 265         struct mux_chip **ptr;
 266         int res;
 267
 268         ptr = devres_alloc(devm_mux_chip_reg_release, sizeof(*ptr), GFP_KERNEL);
 269         if (!ptr)
 270                 return -ENOMEM;
 271
 272         res = mux_chip_register(mux_chip);
 273         if (res) {
 274                 devres_free(ptr);
 275                 return res;
 276         }
 277
 278         *ptr = mux_chip;
 279         devres_add(dev, ptr);
 280
 281         return res;
 282 }
 283 EXPORT_SYMBOL_GPL(devm_mux_chip_register);
 284
 285 /**
 286  * mux_control_states() - Query the number of multiplexer states.
 287  * @mux: The mux-control to query.
 288  *
 289  * Return: The number of multiplexer states.
 290  */
 291 unsigned int mux_control_states(struct mux_control *mux)
 292 {
 293         return mux->states;
 294 }
 295 EXPORT_SYMBOL_GPL(mux_control_states);
 296
 297 /*
 298  * The mux->lock must be down when calling this function.
 299  */
 300 static int __mux_control_select(struct mux_control *mux, int state)
 301 {
 302         int ret;
 303
 304         if (WARN_ON(state < 0 || state >= mux->states))
 305                 return -EINVAL;
 306
 307         if (mux->cached_state == state)
 308                 return 0;
 309
 310         ret = mux_control_set(mux, state);
 311         if (ret >= 0)
 312                 return 0;
 313
 314         /* The mux update failed, try to revert if appropriate... */
 315         if (mux->idle_state != MUX_IDLE_AS_IS)
 316                 mux_control_set(mux, mux->idle_state);
 317
 318         return ret;
 319 }
 320
 321 static void mux_control_delay(struct mux_control *mux, unsigned int delay_us)
 322 {
 323         ktime_t delayend;
 324         s64 remaining;
 325
 326         if (!delay_us)
 327                 return;
 328
 329         delayend = ktime_add_us(mux->last_change, delay_us);
 330         remaining = ktime_us_delta(delayend, ktime_get());
 331         if (remaining > 0)
 332                 fsleep(remaining);
 333 }
 334
 335 /**
 336  * mux_control_select_delay() - Select the given multiplexer state.
 337  * @mux: The mux-control to request a change of state from.
 338  * @state: The new requested state.
 339  * @delay_us: The time to delay (in microseconds) if the mux state is changed.
 340  *
 341  * On successfully selecting the mux-control state, it will be locked until
 342  * there is a call to mux_control_deselect(). If the mux-control is already
 343  * selected when mux_control_select() is called, the caller will be blocked
 344  * until mux_control_deselect() is called (by someone else).
 345  *
 346  * Therefore, make sure to call mux_control_deselect() when the operation is
 347  * complete and the mux-control is free for others to use, but do not call
 348  * mux_control_deselect() if mux_control_select() fails.
 349  *
 350  * Return: 0 when the mux-control state has the requested state or a negative
 351  * errno on error.
 352  */
 353 int mux_control_select_delay(struct mux_control *mux, unsigned int state,
 354                              unsigned int delay_us)
 355 {
 356         int ret;
 357
 358         ret = down_killable(&mux->lock);
 359         if (ret < 0)
 360                 return ret;
 361
 362         ret = __mux_control_select(mux, state);
 363         if (ret >= 0)
 364                 mux_control_delay(mux, delay_us);
 365
 366         if (ret < 0)
 367                 up(&mux->lock);
 368
 369         return ret;
 370 }
 371 EXPORT_SYMBOL_GPL(mux_control_select_delay);
 372
 373 /**
 374  * mux_control_try_select_delay() - Try to select the given multiplexer state.
 375  * @mux: The mux-control to request a change of state from.
 376  * @state: The new requested state.
 377  * @delay_us: The time to delay (in microseconds) if the mux state is changed.
 378  *
 379  * On successfully selecting the mux-control state, it will be locked until
 380  * mux_control_deselect() called.
 381  *
 382  * Therefore, make sure to call mux_control_deselect() when the operation is
 383  * complete and the mux-control is free for others to use, but do not call
 384  * mux_control_deselect() if mux_control_try_select() fails.
 385  *
 386  * Return: 0 when the mux-control state has the requested state or a negative
 387  * errno on error. Specifically -EBUSY if the mux-control is contended.
 388  */
 389 int mux_control_try_select_delay(struct mux_control *mux, unsigned int state,
 390                                  unsigned int delay_us)
 391 {
 392         int ret;
 393
 394         if (down_trylock(&mux->lock))
 395                 return -EBUSY;
 396
 397         ret = __mux_control_select(mux, state);
 398         if (ret >= 0)
 399                 mux_control_delay(mux, delay_us);
 400
 401         if (ret < 0)
 402                 up(&mux->lock);
 403
 404         return ret;
 405 }
 406 EXPORT_SYMBOL_GPL(mux_control_try_select_delay);
 407
 408 /**
 409  * mux_control_deselect() - Deselect the previously selected multiplexer state.
 410  * @mux: The mux-control to deselect.
 411  *
 412  * It is required that a single call is made to mux_control_deselect() for
 413  * each and every successful call made to either of mux_control_select() or
 414  * mux_control_try_select().
 415  *
 416  * Return: 0 on success and a negative errno on error. An error can only
 417  * occur if the mux has an idle state. Note that even if an error occurs, the
 418  * mux-control is unlocked and is thus free for the next access.
 419  */
 420 int mux_control_deselect(struct mux_control *mux)
 421 {
 422         int ret = 0;
 423
 424         if (mux->idle_state != MUX_IDLE_AS_IS &&
 425             mux->idle_state != mux->cached_state)
 426                 ret = mux_control_set(mux, mux->idle_state);
 427
 428         up(&mux->lock);
 429
 430         return ret;
 431 }
 432 EXPORT_SYMBOL_GPL(mux_control_deselect);
 433
 434 /* Note this function returns a reference to the mux_chip dev. */
 435 static struct mux_chip *of_find_mux_chip_by_node(struct device_node *np)
 436 {
 437         struct device *dev;
 438
 439         dev = class_find_device_by_of_node(&mux_class, np);
 440
 441         return dev ? to_mux_chip(dev) : NULL;
 442 }
 443
 444 /**
 445  * mux_control_get() - Get the mux-control for a device.
 446  * @dev: The device that needs a mux-control.
 447  * @mux_name: The name identifying the mux-control.
 448  *
 449  * Return: A pointer to the mux-control, or an ERR_PTR with a negative errno.
 450  */
 451 struct mux_control *mux_control_get(struct device *dev, const char *mux_name)
 452 {
 453         struct device_node *np = dev->of_node;
 454         struct of_phandle_args args;
 455         struct mux_chip *mux_chip;
 456         unsigned int controller;
 457         int index = 0;
 458         int ret;
 459
 460         if (mux_name) {
 461                 index = of_property_match_string(np, "mux-control-names",
 462                                                  mux_name);
 463                 if (index < 0) {
 464                         dev_err(dev, "mux controller '%s' not found\n",
 465                                 mux_name);
 466                         return ERR_PTR(index);
 467                 }
 468         }
 469
 470         ret = of_parse_phandle_with_args(np,
 471                                          "mux-controls", "#mux-control-cells",
 472                                          index, &args);
 473         if (ret) {
 474                 dev_err(dev, "%pOF: failed to get mux-control %s(%i)\n",
 475                         np, mux_name ?: "", index);
 476                 return ERR_PTR(ret);
 477         }
 478
 479         mux_chip = of_find_mux_chip_by_node(args.np);
 480         of_node_put(args.np);
 481         if (!mux_chip)
 482                 return ERR_PTR(-EPROBE_DEFER);
 483
 484         if (args.args_count > 1 ||
 485             (!args.args_count && (mux_chip->controllers > 1))) {
 486                 dev_err(dev, "%pOF: wrong #mux-control-cells for %pOF\n",
 487                         np, args.np);
 488                 put_device(&mux_chip->dev);
 489                 return ERR_PTR(-EINVAL);
 490         }
 491
 492         controller = 0;
 493         if (args.args_count)
 494                 controller = args.args[0];
 495
 496         if (controller >= mux_chip->controllers) {
 497                 dev_err(dev, "%pOF: bad mux controller %u specified in %pOF\n",
 498                         np, controller, args.np);
 499                 put_device(&mux_chip->dev);
 500                 return ERR_PTR(-EINVAL);
 501         }
 502
 503         return &mux_chip->mux[controller];
 504 }
 505 EXPORT_SYMBOL_GPL(mux_control_get);
 506
 507 /**
 508  * mux_control_put() - Put away the mux-control for good.
 509  * @mux: The mux-control to put away.
 510  *
 511  * mux_control_put() reverses the effects of mux_control_get().
 512  */
 513 void mux_control_put(struct mux_control *mux)
 514 {
 515         put_device(&mux->chip->dev);
 516 }
 517 EXPORT_SYMBOL_GPL(mux_control_put);
 518
 519 static void devm_mux_control_release(struct device *dev, void *res)
 520 {
 521         struct mux_control *mux = *(struct mux_control **)res;
 522
 523         mux_control_put(mux);
 524 }
 525
 526 /**
 527  * devm_mux_control_get() - Get the mux-control for a device, with resource
 528  *                          management.
 529  * @dev: The device that needs a mux-control.
 530  * @mux_name: The name identifying the mux-control.
 531  *
 532  * Return: Pointer to the mux-control, or an ERR_PTR with a negative errno.
 533  */
 534 struct mux_control *devm_mux_control_get(struct device *dev,
 535                                          const char *mux_name)
 536 {
 537         struct mux_control **ptr, *mux;
 538
 539         ptr = devres_alloc(devm_mux_control_release, sizeof(*ptr), GFP_KERNEL);
 540         if (!ptr)
 541                 return ERR_PTR(-ENOMEM);
 542
 543         mux = mux_control_get(dev, mux_name);
 544         if (IS_ERR(mux)) {
 545                 devres_free(ptr);
 546                 return mux;
 547         }
 548
 549         *ptr = mux;
 550         devres_add(dev, ptr);
 551
 552         return mux;
 553 }
 554 EXPORT_SYMBOL_GPL(devm_mux_control_get);
 555
 556 /*
 557  * Using subsys_initcall instead of module_init here to try to ensure - for
 558  * the non-modular case - that the subsystem is initialized when mux consumers
 559  * and mux controllers start to use it.
 560  * For the modular case, the ordering is ensured with module dependencies.
 561  */
 562 subsys_initcall(mux_init);
 563 module_exit(mux_exit);
 564
 565 MODULE_DESCRIPTION("Multiplexer subsystem");
 566 MODULE_AUTHOR("Peter Rosin <peda@axentia.se>");
 567 MODULE_LICENSE("GPL v2");