1
2# The Device Protocol
3
4Device drivers implement a set of hooks (methods) to support the
5operations that may be done on the devices that they publish.
6
7These are described below, including the action that is taken
8by the default implementation that is used for each hook if the
9driver does not provide its own implementation.
10
11## version
12This field must be set to `DEVICE_OPS_VERSION`
13```
14uint64_t version;
15```
16
17## open
18
19The open hook is called when a device is opened via the device filesystem,
20or when an existing open connection to a device is cloned (for example,
21when a device fd is shared with another process).  The default open hook,
22if a driver does not implement one, simply returns **ZX_OK**.
23
24Drivers may want to implement open to disallow simultaneous access (by
25failing if the device is already open), or to return a new **device instance**
26instead.
27
28The optional *dev_out* parameter allows a device to create and return a
29**device instance** child device, which can be used to manage per-instance
30state instead of all client connections interacting with the device itself.
31A child created for return as an instance **must** be created with the
32**DEVICE_ADD_INSTANCE** flag set in the arguments to **device_add()**.
33
34```
35zx_status_t (*open)(void* ctx, zx_device_t** dev_out, uint32_t flags);
36```
37
38## open_at
39The open_at hook is called in the event that the open path to the device
40contains segments after the device name itself.  For example, if a device
41exists as `/dev/misc/foo` and an attempt is made to `open("/dev/misc/foo/bar",...)`,
42the open_at hook would be invoked with a *path* of `"bar"`.
43
44The default open_at implementation returns **ZX_ERR_NOT_SUPPORTED**
45
46```
47zx_status_t (*open_at)(void* ctx, zx_device_t** dev_out, const char* path, uint32_t flags);
48```
49
50## close
51The close hook is called when a connection to a device is closed.  These
52calls will balance the calls to open or open_at.
53
54**Note:** If open or open_at return a **device instance**, the balancing close
55hook that is called is the close hook on the **instance**, not the parent.
56
57The default close implementation returns **ZX_OK**.
58```
59zx_status_t (*close)(void* ctx, uint32_t flags);
60```
61
62## unbind
63The unbind hook is called when the parent of this device is being removed (due
64to hot unplug, fatal error, etc).  At the point unbind is called, it is not
65possible for further open or open_at calls to occur, but io operations, etc
66may continue until those client connections are closed.
67
68The driver should adjust its state to encourage its client connections to close
69(cause IO to error out, etc), and call **device_remove()** on itself when ready.
70
71The driver must continue to handle all device hooks until the **release** hook
72is invoked.
73
74```
75void (*unbind)(void* ctx);
76```
77
78## release
79The release hook is called after this device has been removed by **device_remove()**
80and all open client connections have been closed, and all child devices have been
81removed and released.
82
83At the point release is invoked, the driver will not receive any further calls
84and absolutely must not use the underlying **zx_device_t** once this method
85returns.
86
87The driver must free all memory and release all resources related to this device
88before returning.
89```
90void (*release)(void* ctx);
91```
92
93## read
94The read hook is an attempt to do a non-blocking read operation.
95
96On success *actual* must be set to the number of bytes read (which may be less
97than the number requested in *count*), and return **ZX_OK**.
98
99A successful read of 0 bytes is generally treated as an End Of File notification
100by clients.
101
102If no data is available now, **ZX_ERR_SHOULD_WAIT** must be returned and when
103data becomes available `device_state_set(DEVICE_STATE_READABLE)` may be used to
104signal waiting clients.
105
106This hook **must not block**.
107
108The default read implementation returns **ZX_ERR_NOT_SUPPORTED**.
109
110```
111zx_status_t (*read)(void* ctx, void* buf, size_t count,
112                    zx_off_t off, size_t* actual);
113```
114
115## write
116The write hook is an attempt to do a non-blocking write operation.
117
118On success *actual* must be set to the number of bytes written (which may be
119less than the number requested in *count*), and **ZX_OK** should be returned.
120
121If it is not possible to write data at present **ZX_ERR_SHOULD_WAIT** must
122be returned and when it is again possible to write,
123`device_state_set(DEVICE_STATE_WRITABLE)` may be used to signal waiting clients.
124
125This hook **must not block**.
126
127The default write implementation returns **ZX_ERR_NOT_SUPPORTED**.
128
129```
130zx_status_t (*write)(void* ctx, const void* buf, size_t count,
131                     zx_off_t off, size_t* actual);
132```
133
134## get_size
135If the device is seekable, the get_size hook should return the size of the device.
136
137This is the offset at which no more reads or writes are possible.
138
139The default implementation returns 0.
140```
141zx_off_t (*get_size)(void* ctx);
142```
143
144## ioctl
145The ioctl hook allows support for device-specific operations.
146
147These, like read and write, must not block.
148
149On success, **ZX_OK** must be returned and *out_actual* must be set
150to the number of output bytes provided (0 if none).
151
152The default ioctl implementation returns **ZX_ERR_NOT_SUPPORTED**.
153```
154zx_status_t (*ioctl)(void* ctx, uint32_t op,
155                     const void* in_buf, size_t in_len,
156                     void* out_buf, size_t out_len, size_t* out_actual);
157```
158
159#### Device State Bits
160```
161#define DEV_STATE_READABLE DEVICE_SIGNAL_READABLE
162#define DEV_STATE_WRITABLE DEVICE_SIGNAL_WRITABLE
163#define DEV_STATE_ERROR DEVICE_SIGNAL_ERROR
164#define DEV_STATE_HANGUP DEVICE_SIGNAL_HANGUP
165#define DEV_STATE_OOB DEVICE_SIGNAL_OOB
166```
167
168#### device_state_set
169```
170void device_state_set(zx_device_t* dev, zx_signals_t stateflag);
171```
172