1
2
3<!--
4    (C) Copyright 2018 The Fuchsia Authors. All rights reserved.
5    Use of this source code is governed by a BSD-style license that can be
6    found in the LICENSE file.
7-->
8
9# Advanced Topics and Tips
10
11This document is part of the [Driver Development Kit tutorial](ddk-tutorial.md) documentation.
12
13## Taking a long time to initialize
14
15What if your device takes a long time to initialize?
16When we discussed the **null_bind()** function above, we indicated that a successful
17return told the device manager that the driver is now associated with the device.
18We can't spend a lot of time in the bind function; we're basically expected to initialize
19our device, publish it, and be done.
20
21But your device might need to perform a lengthy initialization operation, such as:
22
23*   enumerate hardware points
24*   load firmware
25*   negotiate a protocol
26
27and so on, which might take a long time to do.
28
29You can publish your device as "invisible" using the `DEVICE_ADD_INVISIBLE` flag.
30This meets the requirements for the binding function, but nobody is able to use
31your device (because nobody knows about it yet, because it's not visible).
32Now your device can perform the long operations via a background thread.
33
34When your device is ready to service client requests, call
35**device_make_visible()**
36which will cause it to appear in the pathname space.
37
38### Power savings
39
40Two callouts, **suspend()** and **resume()**, are available for your device in
41order to support power or other resource saving features.
42
43Both take a device context pointer and a flags argument, but the flags argument is
44used only in the suspend case.
45
46Flag                                | Meaning
47------------------------------------|------------------------------------------------------------
48`DEVICE_SUSPEND_FLAG_REBOOT`        | The driver should shut itself down in preparation for a reboot or shutdown of the machine
49`DEVICE_SUSPEND_FLAG_REBOOT_BOOTLOADER` | ?
50`DEVICE_SUSPEND_FLAG_REBOOT_RECOVERY`   | ?
51`DEVICE_SUSPEND_FLAG_POWEROFF`      | The driver should shut itself down in preparation for power off
52`DEVICE_SUSPEND_FLAG_MEXEC`         | @@@ almost nobody uses this except for a graphics controller, what does it do? @@@
53`DEVICE_SUSPEND_FLAG_SUSPEND_RAM`   | The driver should arrange so that it can be restarted from RAM
54
55> @@@ Yeah, I'm just guessing on the flags; they're used so little...
56
57For documentation purposes, what should I write?
58That they are just hints, or that you *must* do something because of a given flag, or ... ?
59
60## Reference: Support functions
61
62This section lists support functions that are provided for your driver to use.
63
64### Accessor functions
65
66The context block that's passed as the first argument to your driver's protocol functions
67is an opaque data structure.
68This means that in order to access the data elements, you need to call an accessor function:
69
70Function                | Purpose
71------------------------|-------------------------------------------
72**device_get_name()**        | Retrieves the name of the device
73**device_get_parent()**      | Retrieves the parent device of the device
74
75### Administrative functions
76
77The following functions are used to administer the device:
78
79Function                    | Purpose
80----------------------------|-------------------------------------------
81**device_add()**                 | Adds a device to a parent
82**device_make_visible()**        | Makes a device visible
83**device_remove()**              | Removes a device from a parent
84
85### Signalling
86
87The following functions are used to set the state of a device:
88
89Function                | Purpose
90------------------------|-------------------------------------------
91**device_state_set()**       | sets the given signal(s) on the device
92**device_state_clr()**       | clears the given signal(s) on the device
93
94We saw these in the `/dev/misc/demo-fifo` handler above.
95
96@@@ Notes only @@@
97
98This section is great for things like open_at(), talking about buffer management,
99threading, best practices, advanced options for device_add(), and so on.
100I think it can be somewhere between the man page ("printf is used to print a string
101and takes the following parameters") and an application note &mdash; I want to see
102examples of how to use the functions, what the arguments mean, what the impact of
103various design decisions is, that kind of thing.
104
105