root/drivers/mux/core.c

DEFINITIONS

1. mux_init
2. mux_exit
3. mux_chip_release
4. mux_chip_alloc
5. mux_control_set
6. mux_chip_register
7. mux_chip_unregister
8. mux_chip_free
9. devm_mux_chip_release
10. devm_mux_chip_alloc
11. devm_mux_chip_reg_release
12. devm_mux_chip_register
13. mux_control_states
14. __mux_control_select
15. mux_control_select
16. mux_control_try_select
17. mux_control_deselect
18. of_find_mux_chip_by_node
19. mux_control_get
20. mux_control_put
21. devm_mux_control_release
22. devm_mux_control_get

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