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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<table class="head">
<tr>
<td class="head-ltitle">HIDRAW(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">HIDRAW(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">hidraw</code> — <span class="Nd">Raw
Access to HID devices</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp">To compile this driver into the kernel, place the following line
in your kernel configuration file:</p>
<div class="Bd Pp Bd-indent"><code class="Cd">device hidraw</code>
<br/>
<code class="Cd">device hid</code>
<br/>
<code class="Cd">device hidbus</code></div>
<p class="Pp">Alternatively, to load the driver as a module at boot time, place
the following line in <a class="Xr">loader.conf(5)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>hidraw_load="YES"</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">hidraw</code> driver provides a raw interface
to Human Interface Devices (HIDs). The reports are sent to and received from
the device unmodified.</p>
<p class="Pp">The device handles 2 sets of <a class="Xr">ioctl(2)</a> calls:</p>
<p class="Pp"><span class="Ux">FreeBSD</span> <a class="Xr">uhid(4)</a>
-compatible calls:</p>
<dl class="Bl-tag">
<dt id="HIDRAW_GET_REPORT_ID"><a class="permalink" href="#HIDRAW_GET_REPORT_ID"><code class="Dv">HIDRAW_GET_REPORT_ID</code></a>
(<var class="Vt">int</var>)</dt>
<dd>Get the report identifier used by this HID report.</dd>
<dt id="HIDRAW_GET_REPORT_DESC"><a class="permalink" href="#HIDRAW_GET_REPORT_DESC"><code class="Dv">HIDRAW_GET_REPORT_DESC</code></a>
(<var class="Vt">struct hidraw_gen_descriptor</var>)</dt>
<dd>Get the HID report descriptor. Copies a maximum of
<var class="Va">hgd_maxlen</var> bytes of the report descriptor data into
the memory specified by <var class="Va">hgd_data</var>. Upon return
<var class="Va">hgd_actlen</var> is set to the number of bytes copied.
Using this descriptor the exact layout and meaning of data to/from the
device can be found. The report descriptor is delivered without any
processing.
<div class="Bd Pp Li">
<pre>struct hidraw_gen_descriptor {
void *hgd_data;
uint16_t hgd_maxlen;
uint16_t hgd_actlen;
uint8_t hgd_report_type;
...
};</pre>
</div>
</dd>
<dt id="HIDRAW_SET_IMMED"><a class="permalink" href="#HIDRAW_SET_IMMED"><code class="Dv">HIDRAW_SET_IMMED</code></a>
(<var class="Vt">int</var>)</dt>
<dd>Sets the device in a mode where each <a class="Xr">read(2)</a> will return
the current value of the input report. Normally a
<a class="Xr">read(2)</a> will only return the data that the device
reports on its interrupt pipe. This call may fail if the device does not
support this feature.</dd>
<dt id="HIDRAW_GET_REPORT"><a class="permalink" href="#HIDRAW_GET_REPORT"><code class="Dv">HIDRAW_GET_REPORT</code></a>
(<var class="Vt">struct hidraw_gen_descriptor</var>)</dt>
<dd>Get a report from the device without waiting for data on the interrupt
pipe. Copies a maximum of <var class="Va">hgd_maxlen</var> bytes of the
report data into the memory specified by <var class="Va">hgd_data</var>.
Upon return <var class="Va">hgd_actlen</var> is set to the number of bytes
copied. The <var class="Va">hgd_report_type</var> field indicates which
report is requested. It should be
<code class="Dv">HID_INPUT_REPORT</code>,
<code class="Dv">HID_OUTPUT_REPORT</code>, or
<code class="Dv">HID_FEATURE_REPORT</code>. On a device which uses
numbered reports, the first byte of the returned data is the report
number. The report data begins from the second byte. For devices which do
not use numbered reports, the report data begins at the first byte. This
call may fail if the device does not support this feature.</dd>
<dt id="HIDRAW_SET_REPORT"><a class="permalink" href="#HIDRAW_SET_REPORT"><code class="Dv">HIDRAW_SET_REPORT</code></a>
(<var class="Vt">struct hidraw_gen_descriptor</var>)</dt>
<dd>Set a report in the device. The <var class="Va">hgd_report_type</var>
field indicates which report is to be set. It should be
<code class="Dv">HID_INPUT_REPORT</code>,
<code class="Dv">HID_OUTPUT_REPORT</code>, or
<code class="Dv">HID_FEATURE_REPORT</code>. The value of the report is
specified by the <var class="Va">hgd_data</var> and the
<var class="Va">hgd_maxlen</var> fields. On a device which uses numbered
reports, the first byte of data to be sent is the report number. The
report data begins from the second byte. For devices which do not use
numbered reports, the report data begins at the first byte. This call may
fail if the device does not support this feature.</dd>
<dt id="HIDRAW_GET_DEVICEINFO"><a class="permalink" href="#HIDRAW_GET_DEVICEINFO"><code class="Dv">HIDRAW_GET_DEVICEINFO</code></a>
(<var class="Vt">struct hidraw_device_info</var>)</dt>
<dd>Returns information about the device, like vendor ID and product ID. This
call will not issue any hardware transfers.</dd>
</dl>
<p class="Pp">Linux <code class="Nm">hidraw</code> -compatible calls:</p>
<dl class="Bl-tag">
<dt id="HIDIOCGRDESCSIZE"><a class="permalink" href="#HIDIOCGRDESCSIZE"><code class="Dv">HIDIOCGRDESCSIZE</code></a>
(<var class="Vt">int</var>)</dt>
<dd>Get the HID report descriptor size. Returns the size of the device report
descriptor to use with <code class="Dv">HIDIOCGRDESC</code>
<a class="Xr">ioctl(2)</a>.</dd>
<dt id="HIDIOCGRDESC"><a class="permalink" href="#HIDIOCGRDESC"><code class="Dv">HIDIOCGRDESC</code></a>
(<var class="Vt">struct hidraw_report_descriptor</var>)</dt>
<dd>Get the HID report descriptor. Copies a maximum of
<var class="Va">size</var> bytes of the report descriptor data into the
memory specified by <var class="Va">value</var>.
<div class="Bd Pp Li">
<pre>struct hidraw_report_descriptor {
uint32_t size;
uint8_t value[HID_MAX_DESCRIPTOR_SIZE];
};</pre>
</div>
</dd>
<dt id="HIDIOCGRAWINFO"><a class="permalink" href="#HIDIOCGRAWINFO"><code class="Dv">HIDIOCGRAWINFO</code></a>
(<var class="Vt">struct hidraw_devinfo</var>)</dt>
<dd>Get structure containing the bus type, the vendor ID (VID), and product ID
(PID) of the device. The bus type can be one of:
<code class="Dv">BUS_USB</code> or <code class="Dv">BUS_I2C</code> which
are defined in dev/evdev/input.h.
<div class="Bd Pp Li">
<pre>struct hidraw_devinfo {
uint32_t bustype;
int16_t vendor;
int16_t product;
};</pre>
</div>
</dd>
<dt id="HIDIOCGRAWNAME(len)"><a class="permalink" href="#HIDIOCGRAWNAME(len)"><code class="Dv">HIDIOCGRAWNAME(len)</code></a>
(<var class="Vt">char[] buf</var>)</dt>
<dd>Get device description. Copies a maximum of <var class="Va">len</var>
bytes of the device description previously set with
<a class="Xr">device_set_desc(9)</a> procedure into the memory specified
by <var class="Va">buf</var>.</dd>
<dt id="HIDIOCGRAWPHYS(len)"><a class="permalink" href="#HIDIOCGRAWPHYS(len)"><code class="Dv">HIDIOCGRAWPHYS(len)</code></a>
(<var class="Vt">char[] buf</var>)</dt>
<dd>Get the newbus path to the device. Copies a maximum of
<var class="Va">len</var> bytes of the newbus device path into the memory
specified by <var class="Va">buf</var>.</dd>
<dt id="HIDIOCGFEATURE(len)"><a class="permalink" href="#HIDIOCGFEATURE(len)"><code class="Dv">HIDIOCGFEATURE(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd style="width: auto;"> </dd>
<dt id="HIDIOCGINPUT(len)"><a class="permalink" href="#HIDIOCGINPUT(len)"><code class="Dv">HIDIOCGINPUT(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd style="width: auto;"> </dd>
<dt id="HIDIOCGOUTPUT(len)"><a class="permalink" href="#HIDIOCGOUTPUT(len)"><code class="Dv">HIDIOCGOUTPUT(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd>Get respectively a feature, input or output report from the device. Copies
a maximum of <var class="Va">len</var> bytes of the report data into the
memory specified by <var class="Va">buf</var>. The first byte of the
supplied buffer should be set to the report number of the requested
report. For devices which do not use numbered reports, set the first byte
to 0. The report will be returned starting at the first byte of the buffer
(ie: the report number is not returned). This call may fail if the device
does not support this feature.</dd>
<dt id="HIDIOCSFEATURE(len)"><a class="permalink" href="#HIDIOCSFEATURE(len)"><code class="Dv">HIDIOCSFEATURE(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd style="width: auto;"> </dd>
<dt id="HIDIOCSINPUT(len)"><a class="permalink" href="#HIDIOCSINPUT(len)"><code class="Dv">HIDIOCSINPUT(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd style="width: auto;"> </dd>
<dt id="HIDIOCSOUTPUT(len)"><a class="permalink" href="#HIDIOCSOUTPUT(len)"><code class="Dv">HIDIOCSOUTPUT(len)</code></a>
(<var class="Vt">void[] buf</var>)</dt>
<dd>Set respectively a feature, input or output Report in the device. The
value of the report is specified by the <var class="Va">buf</var> and the
<var class="Va">len</var> parameters. Set the first byte of the supplied
buffer to the report number. For devices which do not use numbered
reports, set the first byte to 0. The report data begins in the second
byte. Make sure to set len accordingly, to one more than the length of the
report (to account for the report number). This call may fail if the
device does not support this feature.</dd>
</dl>
<p class="Pp">Use <a class="Xr">read(2)</a> to get data from the device. Data
should be read in chunks of the size prescribed by the report descriptor. On
a device which uses numbered reports, the first byte of the returned data is
the report number. The report data begins from the second byte. For devices
which do not use numbered reports, the report data begins at the first
byte.</p>
<p class="Pp">Use <a class="Xr">write(2)</a> to send data to the device. Data
should be written in chunks of the size prescribed by the report descriptor.
The first byte of the buffer passed to <a class="Xr">write(2)</a> should be
set to the report number. If the device does not use numbered reports, there
are 2 operation modes: <code class="Nm">hidraw</code> mode and
<a class="Xr">uhid(4)</a> mode. In the <code class="Nm">hidraw</code> mode,
the first byte should be set to 0 and the report data itself should begin at
the second byte. In the <a class="Xr">uhid(4)</a> mode, the report data
should begin at the first byte. The modes can be switched with issuing one
of <code class="Dv">HIDIOCGRDESC</code> or
<code class="Dv">HID_GET_REPORT_DESC</code> <a class="Xr">ioctl(2)</a>
accordingly. Default mode is <code class="Nm">hidraw</code>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL
VARIABLES</a></h1>
<p class="Pp">The following variables are available as both
<a class="Xr">sysctl(8)</a> variables and <a class="Xr">loader(8)</a>
tunables:</p>
<dl class="Bl-tag">
<dt id="hw.hid.hidraw.debug"><var class="Va">hw.hid.hidraw.debug</var></dt>
<dd>Debug output level, where 0 is debugging disabled and larger values
increase debug message verbosity. Default is 0.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag">
<dt><span class="Pa">/dev/hidraw?</span></dt>
<dd style="width: auto;"> </dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">usbhidctl(1)</a>, <a class="Xr">hid(4)</a>,
<a class="Xr">hidbus(4)</a>, <a class="Xr">uhid(4)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <a class="Xr">uhid(4)</a> driver appeared in
<span class="Ux">NetBSD 1.4</span>. <code class="Nm">hidraw</code> protocol
support was added in <span class="Ux">FreeBSD 13</span> by
<span class="An">Vladimir Kondratyev</span>
<<a class="Mt" href="mailto:wulf@FreeBSD.org">wulf@FreeBSD.org</a>>.
This manual page was adopted from <span class="Ux">NetBSD</span> by
<span class="An">Tom Rhodes</span>
<<a class="Mt" href="mailto:trhodes@FreeBSD.org">trhodes@FreeBSD.org</a>>
in April 2002.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">April 27, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
