0001 =============================
0002 Device Driver Design Patterns
0003 =============================
0004
0005 This document describes a few common design patterns found in device drivers.
0006 It is likely that subsystem maintainers will ask driver developers to
0007 conform to these design patterns.
0008
0009 1. State Container
0010 2. container_of()
0011
0012
0013 1. State Container
0014 ~~~~~~~~~~~~~~~~~~
0015
0016 While the kernel contains a few device drivers that assume that they will
0017 only be probed() once on a certain system (singletons), it is custom to assume
0018 that the device the driver binds to will appear in several instances. This
0019 means that the probe() function and all callbacks need to be reentrant.
0020
0021 The most common way to achieve this is to use the state container design
0022 pattern. It usually has this form::
0023
0024 struct foo {
0025 spinlock_t lock; /* Example member */
0026 (...)
0027 };
0028
0029 static int foo_probe(...)
0030 {
0031 struct foo *foo;
0032
0033 foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
0034 if (!foo)
0035 return -ENOMEM;
0036 spin_lock_init(&foo->lock);
0037 (...)
0038 }
0039
0040 This will create an instance of struct foo in memory every time probe() is
0041 called. This is our state container for this instance of the device driver.
0042 Of course it is then necessary to always pass this instance of the
0043 state around to all functions that need access to the state and its members.
0044
0045 For example, if the driver is registering an interrupt handler, you would
0046 pass around a pointer to struct foo like this::
0047
0048 static irqreturn_t foo_handler(int irq, void *arg)
0049 {
0050 struct foo *foo = arg;
0051 (...)
0052 }
0053
0054 static int foo_probe(...)
0055 {
0056 struct foo *foo;
0057
0058 (...)
0059 ret = request_irq(irq, foo_handler, 0, "foo", foo);
0060 }
0061
0062 This way you always get a pointer back to the correct instance of foo in
0063 your interrupt handler.
0064
0065
0066 2. container_of()
0067 ~~~~~~~~~~~~~~~~~
0068
0069 Continuing on the above example we add an offloaded work::
0070
0071 struct foo {
0072 spinlock_t lock;
0073 struct workqueue_struct *wq;
0074 struct work_struct offload;
0075 (...)
0076 };
0077
0078 static void foo_work(struct work_struct *work)
0079 {
0080 struct foo *foo = container_of(work, struct foo, offload);
0081
0082 (...)
0083 }
0084
0085 static irqreturn_t foo_handler(int irq, void *arg)
0086 {
0087 struct foo *foo = arg;
0088
0089 queue_work(foo->wq, &foo->offload);
0090 (...)
0091 }
0092
0093 static int foo_probe(...)
0094 {
0095 struct foo *foo;
0096
0097 foo->wq = create_singlethread_workqueue("foo-wq");
0098 INIT_WORK(&foo->offload, foo_work);
0099 (...)
0100 }
0101
0102 The design pattern is the same for an hrtimer or something similar that will
0103 return a single argument which is a pointer to a struct member in the
0104 callback.
0105
0106 container_of() is a macro defined in <linux/kernel.h>
0107
0108 What container_of() does is to obtain a pointer to the containing struct from
0109 a pointer to a member by a simple subtraction using the offsetof() macro from
0110 standard C, which allows something similar to object oriented behaviours.
0111 Notice that the contained member must not be a pointer, but an actual member
0112 for this to work.
0113
0114 We can see here that we avoid having global pointers to our struct foo *
0115 instance this way, while still keeping the number of parameters passed to the
0116 work function to a single pointer.
