Newer
Older
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
Introduction
============
This directory contains Device Tree overlays. Device Tree makes it possible
to support many hardware configurations with a single kernel and without the
need to explicitly load or blacklist kernel modules. Note that this isn't a
"pure" Device Tree configuration (c.f. MACH_BCM2835) - some on-board devices
are still configured by the board support code, but the intention is to
eventually reach that goal.
On Raspberry Pi, Device Tree usage is controlled from /boot/config.txt. By
default, the Raspberry Pi kernel boots with device tree enabled. You can
completely disable DT usage (for now) by adding:
device_tree=
to your config.txt, which should cause your Pi to revert to the old way of
doing things after a reboot.
In /boot you will find a .dtb for each base platform. This describes the
hardware that is part of the Raspberry Pi board. The loader (start.elf and its
siblings) selects the .dtb file appropriate for the platform by name, and reads
it into memory. At this point, all of the optional interfaces (i2c, i2s, spi)
are disabled, but they can be enabled using Device Tree parameters:
dtparam=i2c=on,i2s=on,spi=on
However, this shouldn't be necessary in many use cases because loading an
overlay that requires one of those interfaces will cause it to be enabled
automatically, and it is advisable to only enable interfaces if they are
needed.
Configuring additional, optional hardware is done using Device Tree overlays
(see below).
GPIO numbering uses the hardware pin numbering scheme (aka BCM scheme) and
not the physical pin numbers.
raspi-config
============
The Advanced Options section of the raspi-config utility can enable and disable
Device Tree use, as well as toggling the I2C and SPI interfaces. Note that it
is possible to both enable an interface and blacklist the driver, if for some
reason you should want to defer the loading.
Modules
=======
As well as describing the hardware, Device Tree also gives enough information
to allow suitable driver modules to be located and loaded, with the corollary
that unneeded modules are not loaded. As a result it should be possible to
remove lines from /etc/modules, and /etc/modprobe.d/raspi-blacklist.conf can
have its contents deleted (or commented out).
Using Overlays
==============
Overlays are loaded using the "dtoverlay" config.txt setting. As an example,
consider I2C Real Time Clock drivers. In the pre-DT world these would be loaded
by writing a magic string comprising a device identifier and an I2C address to
a special file in /sys/class/i2c-adapter, having first loaded the driver for
the I2C interface and the RTC device - something like this:
modprobe i2c-bcm2835
modprobe rtc-ds1307
echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-1/new_device
With DT enabled, this becomes a line in config.txt:
dtoverlay=i2c-rtc,ds1307
This causes the file /boot/overlays/i2c-rtc.dtbo to be loaded and a "node"
describing the DS1307 I2C device to be added to the Device Tree for the Pi. By
default it usees address 0x68, but this can be modified with an additional DT
parameter:
dtoverlay=i2c-rtc,ds1307,addr=0x68
Parameters usually have default values, although certain parameters are
mandatory. See the list of overlays below for a description of the parameters
and their defaults.
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
Making new Overlays based on existing Overlays
==============================================
Recent overlays have been designed in a more general way, so that they can be
adapted to hardware by changing their parameters. When you have additional
hardware with more than one device of a kind, you end up using the same overlay
multiple times with other parameters, e.g.
# 2 CAN FD interfaces on spi but with different pins
dtoverlay=mcp251xfd,spi0-0,interrupt=25
dtoverlay=mcp251xfd,spi0-1,interrupt=24
# a realtime clock on i2c
dtoverlay=i2c-rtc,pcf85063
While this approach does work, it requires knowledge about the hardware design.
It is more feasible to simplify things for the end user by providing a single
overlay as it is done the traditional way.
A new overlay can be generated by using ovmerge utility.
https://github.com/raspberrypi/utils/blob/master/ovmerge/ovmerge
To generate an overlay for the above configuration we pass the configuration
to ovmerge and add the -c flag.
ovmerge -c mcp251xfd-overlay.dts,spi0-0,interrupt=25 \
mcp251xfd-overlay.dts,spi0-1,interrupt=24 \
i2c-rtc-overlay.dts,pcf85063 \
>> merged-overlay.dts
The -c option writes the command above as a comment into the overlay as
a marker that this overlay is generated and how it was generated.
After compiling the overlay it can be loaded in a single line.
dtoverlay=merged
It does the same as the original configuration but without parameters.
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
The Overlay and Parameter Reference
===================================
N.B. When editing this file, please preserve the indentation levels to make it
simple to parse programmatically. NO HARD TABS.
Name: <The base DTB>
Info: Configures the base Raspberry Pi hardware
Load: <loaded automatically>
Params:
ant1 Select antenna 1 (default). CM4 only.
ant2 Select antenna 2. CM4 only.
noant Disable both antennas. CM4 only.
audio Set to "on" to enable the onboard ALSA audio
interface (default "off")
axiperf Set to "on" to enable the AXI bus performance
monitors.
See /sys/kernel/debug/raspberrypi_axi_monitor
for the results.
eee Enable Energy Efficient Ethernet support for
compatible devices (default "on"). See also
"tx_lpi_timer". Pi3B+ only.
eth_downshift_after Set the number of auto-negotiation failures
after which the 1000Mbps modes are disabled.
Legal values are 2, 3, 4, 5 and 0, where
0 means never downshift (default 2). Pi3B+ only.
eth_led0 Set mode of LED0 - amber on Pi3B+ (default "1"),
green on Pi4 (default "0").
The legal values are:
Pi3B+
0=link/activity 1=link1000/activity
2=link100/activity 3=link10/activity
4=link100/1000/activity 5=link10/1000/activity
6=link10/100/activity 14=off 15=on
Pi4
0=Speed/Activity 1=Speed
2=Flash activity 3=FDX
4=Off 5=On
6=Alt 7=Speed/Flash
8=Link 9=Activity
eth_led1 Set mode of LED1 - green on Pi3B+ (default "6"),
amber on Pi4 (default "8"). See eth_led0 for
legal values.
eth_max_speed Set the maximum speed a link is allowed
to negotiate. Legal values are 10, 100 and
1000 (default 1000). Pi3B+ only.
i2c_arm Set to "on" to enable the ARM's i2c interface
(default "off")
i2c_vc Set to "on" to enable the i2c interface
usually reserved for the VideoCore processor
(default "off")
i2c An alias for i2c_arm
i2c_arm_baudrate Set the baudrate of the ARM's i2c interface
(default "100000")
i2c_vc_baudrate Set the baudrate of the VideoCore i2c interface
(default "100000")
i2c_baudrate An alias for i2c_arm_baudrate
i2s Set to "on" to enable the i2s interface
Loading full blame...