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
|
<table class="head">
<tr>
<td class="head-ltitle">SPIGEN(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">SPIGEN(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">spigen</code> — <span class="Nd">SPI
generic I/O device driver</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 lines
in your kernel configuration file:</p>
<div class="Bd Pp Bd-indent"><code class="Cd">device spi</code>
<br/>
<code class="Cd">device spibus</code>
<br/>
<code class="Cd">device spigen</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>spigen_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">spigen</code> driver provides direct access
to a slave device on the SPI bus. Each instance of a
<code class="Nm">spigen</code> device is associated with a single
chip-select line on the bus, and all I/O performed through that instance is
done with that chip-select line asserted.</p>
<p class="Pp">SPI data transfers are inherently bi-directional; there are no
separate read and write operations. When commands and data are sent to a
device, data also comes back from the device, although in some cases the
data may not be useful (or even documented or predictable for some devices).
Likewise on a read operation, whatever data is in the buffer at the start of
the operation is sent to (and typically ignored by) the device, with each
outgoing byte then replaced in the buffer by the corresponding incoming
byte. Thus, all buffers passed to the transfer functions are both input and
output buffers.</p>
<p class="Pp">The <code class="Nm">spigen</code> driver provides access to the
SPI slave device with the following <a class="Xr">ioctl(2)</a> calls,
defined in
<code class="In"><<a class="In">sys/spigenio.h</a>></code>:</p>
<dl class="Bl-tag">
<dt id="SPIGENIOC_TRANSFER"><a class="permalink" href="#SPIGENIOC_TRANSFER"><code class="Dv">SPIGENIOC_TRANSFER</code></a>
(<var class="Vt">struct spigen_transfer</var>)</dt>
<dd>Transfer a command and optional associated data to/from the device, using
the buffers described by the st_command and st_data fields in the
<var class="Vt">spigen_transfer</var>. Set
<var class="Vt">st_data.iov_len</var> to zero if there is no data
associated with the command.
<div class="Bd Pp Li">
<pre>struct spigen_transfer {
struct iovec st_command;
struct iovec st_data;
};</pre>
</div>
</dd>
<dt id="SPIGENIOC_TRANSFER_MMAPPED"><a class="permalink" href="#SPIGENIOC_TRANSFER_MMAPPED"><code class="Dv">SPIGENIOC_TRANSFER_MMAPPED</code></a>
(<var class="Vt">spigen_transfer_mmapped</var>)</dt>
<dd>Transfer a command and optional associated data to/from the device. The
buffers for the transfer are a previously-mmap'd region. The length of the
command and data within that region are described by the
<var class="Vt">stm_command_length</var> and
<var class="Vt">stm_data_length</var> fields of
<var class="Vt">spigen_transfer_mmapped</var>. If
<var class="Vt">stm_data_length</var> is non-zero, the data appears in the
memory region immediately following the command (that is, at offset
<var class="Vt">stm_command_length</var> from the start of the mapped
region).
<div class="Bd Pp Li">
<pre>struct spigen_transfer_mmapped {
size_t stm_command_length;
size_t stm_data_length;
};</pre>
</div>
</dd>
<dt id="SPIGENIOC_GET_CLOCK_SPEED"><a class="permalink" href="#SPIGENIOC_GET_CLOCK_SPEED"><code class="Dv">SPIGENIOC_GET_CLOCK_SPEED</code></a>
(<var class="Vt">uint32_t</var>)</dt>
<dd>Get the maximum clock speed (bus frequency in Hertz) to be used when
communicating with this slave device.</dd>
<dt id="SPIGENIOC_SET_CLOCK_SPEED"><a class="permalink" href="#SPIGENIOC_SET_CLOCK_SPEED"><code class="Dv">SPIGENIOC_SET_CLOCK_SPEED</code></a>
(<var class="Vt">uint32_t</var>)</dt>
<dd>Set the maximum clock speed (bus frequency in Hertz) to be used when
communicating with this slave device. The setting remains in effect for
subsequent transfers; it is not necessary to reset this before each
transfer. The actual bus frequency may be lower due to hardware
limitations of the SPI bus controller device.</dd>
<dt id="SPIGENIOC_GET_SPI_MODE"><a class="permalink" href="#SPIGENIOC_GET_SPI_MODE"><code class="Dv">SPIGENIOC_GET_SPI_MODE</code></a>
(<var class="Vt">uint32_t</var>)</dt>
<dd>Get the SPI mode (clock polarity and phase) to be used when communicating
with this device.</dd>
<dt id="SPIGENIOC_SET_SPI_MODE"><a class="permalink" href="#SPIGENIOC_SET_SPI_MODE"><code class="Dv">SPIGENIOC_SET_SPI_MODE</code></a>
(<var class="Vt">uint32_t</var>)</dt>
<dd>Set the SPI mode (clock polarity and phase) to be used when communicating
with this device. The setting remains in effect for subsequent transfers;
it is not necessary to reset this before each transfer.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="HINTS_CONFIGURATION"><a class="permalink" href="#HINTS_CONFIGURATION">HINTS
CONFIGURATION</a></h1>
<p class="Pp">On a <a class="Xr">device.hints(5)</a> based system, such as
<code class="Li">MIPS</code>, these values are configurable for
<code class="Nm">spigen</code>:</p>
<dl class="Bl-tag">
<dt id="hint.spigen._d.at"><var class="Va">hint.spigen.%d.at</var></dt>
<dd>The spibus the <code class="Nm">spigen</code> instance is attached
to.</dd>
<dt id="hint.spigen._d.clock"><var class="Va">hint.spigen.%d.clock</var></dt>
<dd>The maximum bus frequency to use when communicating with this device.
Actual bus speed may be lower, depending on the capabilities of the SPI
bus controller hardware.</dd>
<dt id="hint.spigen._d.cs"><var class="Va">hint.spigen.%d.cs</var></dt>
<dd>The chip-select number to assert when performing I/O for this device. Set
the high bit (1 << 31) to invert the logic level of the chip select
line.</dd>
<dt id="hint.spigen._d.mode"><var class="Va">hint.spigen.%d.mode</var></dt>
<dd>The SPI mode (0-3) to use when communicating with this device.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FDT_CONFIGURATION"><a class="permalink" href="#FDT_CONFIGURATION">FDT
CONFIGURATION</a></h1>
<p class="Pp">On an <a class="Xr">fdt(4)</a> based system, the spigen device is
defined as a slave device subnode of the SPI bus controller node. All
properties documented in the <var class="Va">spibus.txt</var> bindings
document can be used with the <code class="Nm">spigen</code> device. The
most commonly-used ones are documented below.</p>
<p class="Pp">The following properties are required in the
<code class="Nm">spigen</code> device subnode:</p>
<dl class="Bl-tag">
<dt id="compatible"><var class="Va">compatible</var></dt>
<dd>Must be the string "freebsd,spigen".</dd>
<dt id="reg"><var class="Va">reg</var></dt>
<dd>Chip select address of device.</dd>
<dt id="spi-max-frequency"><var class="Va">spi-max-frequency</var></dt>
<dd>The maximum bus frequency to use when communicating with this slave
device. Actual bus speed may be lower, depending on the capabilities of
the SPI bus controller hardware.</dd>
</dl>
<p class="Pp">The following properties are optional for the
<code class="Nm">spigen</code> device subnode:</p>
<dl class="Bl-tag">
<dt id="spi-cpha"><var class="Va">spi-cpha</var></dt>
<dd>Empty property indicating the slave device requires shifted clock phase
(CPHA) mode.</dd>
<dt id="spi-cpol"><var class="Va">spi-cpol</var></dt>
<dd>Empty property indicating the slave device requires inverse clock polarity
(CPOL) mode.</dd>
<dt id="spi-cs-high"><var class="Va">spi-cs-high</var></dt>
<dd>Empty property indicating the slave device requires chip select active
high.</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/spigen*</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">fdt(4)</a>, <a class="Xr">device.hints(5)</a>,
<a class="Xr">spi(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">spigen</code> driver appeared in
<span class="Ux">FreeBSD 11.0</span>. FDT support appeared in
<span class="Ux">FreeBSD 11.2</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 21, 2020</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
