aboutsummaryrefslogtreecommitdiff
path: root/Documentation/driver-api/firmware/driver_data.rst
blob: be7c7ff991512a87514588cc3d33d4e47a2b5f00 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
.. _driver_data:

===============
driver_data API
===============

The driver data APIs provides a flexible API for general driver data file
lookups. Its flexibility aims at mitigating collateral evolutions on the kernel
as new functionality is introduced.

Driver data modes of operation
==============================

There are two types of modes of operation for driver data requests:

  * synchronous  - driver_data_request_sync()
  * asynchronous - driver_data_request_async()

Synchronous requests expect requests to be done immediately, asynchronous
requests enable requests to be scheduled for a later time.

Driver data request parameters
==============================

Variations of types of driver data requests are specified by a driver data
request parameter data structure. The flexibility of the API is provided by
expanding the request parameters as new functionality is needed, without
loosely modifying or adding new exported APIs.

driver_data_sync_cbs
--------------------
.. kernel-doc:: include/linux/driver_data.h
   :functions: driver_data_sync_cbs

driver_data_async_cbs
---------------------
.. kernel-doc:: include/linux/driver_data.h
   :functions: driver_data_async_cbs

driver_data_cbs
---------------
.. kernel-doc:: include/linux/driver_data.h
   :functions: driver_data_cbs

driver_data_reqs
----------------
.. kernel-doc:: include/linux/driver_data.h
   :functions: driver_data_reqs

driver_data_req_params
----------------------
.. kernel-doc:: include/linux/driver_data.h
   :functions: driver_data_req_params

Synchronous driver data requests
================================

Synchronous driver data requests will wait until the driver data is found or
until an error is returned.

driver_data_request_sync
------------------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_request_sync

Asynchronous driver data requests
=================================

Asynchronous driver data requests allow driver code to not have to wait
until the driver data or an error is returned. Function callbacks are
required so that when the firmware or an error is found the driver is
informed through the callbacks. Asynchronous driver data requests cannot
be called from atomic contexts.

driver_data_request_async
-------------------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_request_async

Reference counting and releasing the driver data file
=====================================================

The device and module are bumped with reference counts during the driver data
requests. This prevents removal of the device and module making the driver data
request call until the driver data request callbacks have completed, either
synchronously or asynchronously. When synchronous requests are made the
firmware_class is refcounted. When asynchronous requests are made the caller's
module is refcounted. Asynchronous requests do not refcount the firmware_class
module.

The driver data request API enables callers to provide a callback for both
synchronous and asynchronous requests and since consumption can be expected
in these callbacks it frees it for you by default after callback handlers
are issued. If you wish to keep the driver data around after your callbacks
you must specify this through the driver data request parameter data structure.

Driver data private internal functionality
==========================================

This section documents functionality not exposed to users, but important in
understanding how the driver data internals work.

driver_data_mode
----------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_mode

driver_data_priv_reqs
---------------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_priv_reqs

driver_data_priv_params
-----------------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_priv_params

driver_data_params
------------------
.. kernel-doc:: drivers/base/firmware_class.c
   :functions: driver_data_params

Testing the driver_data API
===========================

The driver data API has a selftest driver: lib/test_driver_data.c. The
test_driver_data enables you to build your tests in userspace by exposing knobs
of the exported API in userspace and enabling userspace to configure and
trigger a kernel call. This lets us build most possible test cases of
the kernel APIs from userspace.

The test_driver_data also enables multiple test triggers to be created
enabling testing to be done in parallel, one test interface per test case.

To test an async call one could do::

        echo anything > /lib/firmware/test-driver_data.bin
        echo -n 1 >  /sys/devices/virtual/misc/test_driver_data0/config_async
        echo -n 1 >  /sys/devices/virtual/misc/test_driver_data0/trigger_config

A series of tests have been written to test the driver data API thoroughly.
A respective test case is expected to bet written as new features get added.
For details of existing tests run::

        tools/testing/selftests/firmware/driver_data.sh -l

To see all available options::

        tools/testing/selftests/firmware/driver_data.sh --help

To run a test 0010 case 40 times::

        tools/testing/selftests/firmware/driver_data.sh -c 0010 40

Note that driver_data.sh uses its own temporary custom path for creating and
looking for driver data files, it does this to not overwrite any production
files you might have which may share the same names used by the test shell
script driver_data.sh. If you are not using the driver_data.sh script your
default path will be used.

Tracking development enhancements and ideas
===========================================

To help track ongoing development for firmware_class and related items to
firmware_class refer to the kernel newbies wiki page [0].

[0] http://kernelnewbies.org/KernelProjects/firmware-class-enhancements