Skip to content

Commit a8ff215

Browse files
pelwellpelwell
committed
dtmerge: Add dtoverlay and dtparam tools
Signed-off-by: Phil Elwell <[email protected]>
1 parent a3cd45e commit a8ff215

File tree

11 files changed

+2174
-7
lines changed

11 files changed

+2174
-7
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
A collection of scripts and simple applications
33

44
* [dtmerge](dtmerge/) - A tool for applying compiled DT overlays (`*.dtbo`) to base Device
5-
Tree files (`*.dtb`)
5+
Tree files (`*.dtb`). Also includes the `dtoverlay` and `dtparam` utilities.
66
* [otpset](otpset/) - A short script to help with reading and setting the customer OTP
77
bits.
88
* [overlaycheck](overlaycheck/) - A tool for validating the overlay files and README in a

‎dtmerge/CMakeLists.txt

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,31 @@ cmake_minimum_required(VERSION 3.10)
22

33
include(GNUInstallDirs)
44

5-
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Werror -pedantic")
6-
75
#set project name
86
project(dtmerge)
97

10-
#add executables
11-
add_executable(dtmerge dtmerge.c dtoverlay.c)
12-
target_link_libraries(dtmerge fdt)
8+
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Werror")
9+
10+
if (CMAKE_COMPILER_IS_GNUCC)
11+
add_definitions (-ffunction-sections)
12+
endif ()
13+
14+
add_library (dtovl ${STATIC} dtoverlay.c)
15+
target_link_libraries(dtovl fdt)
16+
17+
add_executable(dtmerge dtmerge.c)
18+
target_link_libraries(dtmerge dtovl)
1319
install(TARGETS dtmerge RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
1420
install(FILES dtmerge.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
21+
22+
add_executable(dtoverlay dtoverlay_main.c utils.c)
23+
target_link_libraries(dtoverlay dtovl)
24+
install(TARGETS dtoverlay RUNTIME DESTINATION bin)
25+
install(FILES dtoverlay.1 DESTINATION man/man1)
26+
27+
add_custom_command(TARGET dtoverlay POST_BUILD COMMAND ln;-sf;dtoverlay;dtparam)
28+
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/dtparam DESTINATION bin)
29+
install(FILES dtparam.1 DESTINATION man/man1)
30+
31+
set(DTOVERLAY_SCRIPTS dtoverlay-pre dtoverlay-post)
32+
install(PROGRAMS ${DTOVERLAY_SCRIPTS} DESTINATION bin)

‎dtmerge/README.md

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11

2-
# dtmerge
2+
# dtmerge, dtoverlay and dtparam
33

44
dtmerge is a tool for applying pre-compiled overlays (`*.dtbo` files) to a
55
base Device Tree file (`*.dtb`).
66

7+
dtoverlay is a tool for applying pre-compiled overlays to a live system.
8+
dtparam is a tool for applying paramaters of the base Device Tree of a live system.
9+
710
**Build Instructions**
811

912
Install the prerequisites with "sudo apt install cmake libfdt-dev" - you need at least version 3.10 of cmake. Run the following commands here, or in the top-level directory to build and install all the utilities:
@@ -24,3 +27,46 @@ Usage:
2427
-d Enable debug output
2528
-h Show this help message
2629
```
30+
```
31+
Usage:
32+
dtoverlay <overlay> [<param>=<val>...]
33+
Add an overlay (with parameters)
34+
dtoverlay -D Dry-run (prepare overlay, but don't apply -
35+
save it as dry-run.dtbo)
36+
dtoverlay -r [<overlay>] Remove an overlay (by name, index or the last)
37+
dtoverlay -R [<overlay>] Remove from an overlay (by name, index or all)
38+
dtoverlay -l List active overlays/params
39+
dtoverlay -a List all overlays (marking the active)
40+
dtoverlay -h Show this usage message
41+
dtoverlay -h <overlay> Display help on an overlay
42+
dtoverlay -h <overlay> <param>.. Or its parameters
43+
where <overlay> is the name of an overlay or 'dtparam' for dtparams
44+
Options applicable to most variants:
45+
-d <dir> Specify an alternate location for the overlays
46+
(defaults to /boot/overlays or /flash/overlays)
47+
-p <string> Force a compatible string for the platform
48+
-v Verbose operation
49+
50+
Adding or removing overlays and parameters requires root privileges.
51+
```
52+
```
53+
Usage:
54+
dtparam Display help on all parameters
55+
dtparam <param>=<val>...
56+
Add an overlay (with parameters)
57+
dtparam -D Dry-run (prepare overlay, but don't apply -
58+
save it as dry-run.dtbo)
59+
dtparam -r [<idx>] Remove an overlay (by index, or the last)
60+
dtparam -R [<idx>] Remove from an overlay (by index, or all)
61+
dtparam -l List active overlays/dtparams
62+
dtparam -a List all overlays/dtparams (marking the active)
63+
dtparam -h Show this usage message
64+
dtparam -h <param>... Display help on the listed parameters
65+
Options applicable to most variants:
66+
-d <dir> Specify an alternate location for the overlays
67+
(defaults to /boot/overlays or /flash/overlays)
68+
-p <string> Force a compatible string for the platform
69+
-v Verbose operation
70+
71+
Adding or removing overlays and parameters requires root privileges.
72+
```

‎dtmerge/dtoverlay-post

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
3+
if ! hash lxpanelctl 2> /dev/null; then
4+
exit 0
5+
fi
6+
7+
CMD="lxpanelctl command volumealsabt start > /dev/null"
8+
9+
for PID in $(pgrep -x lxpanel); do
10+
eval "$(grep -z "DISPLAY=" "/proc/$PID/environ" | tr -d '\0')"
11+
user="$(ps -p "$PID" -o uname=)"
12+
su "$user" -c "$CMD"
13+
done

‎dtmerge/dtoverlay-pre

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
3+
if ! hash lxpanelctl 2> /dev/null; then
4+
exit 0
5+
fi
6+
7+
CMD="lxpanelctl command volumealsabt stop >/dev/null"
8+
9+
for PID in $(pgrep -x lxpanel); do
10+
eval "$(grep -z "DISPLAY=" "/proc/$PID/environ" | tr -d '\0')"
11+
user="$(ps -p "$PID" -o uname=)"
12+
su "$user" -c "$CMD"
13+
done

‎dtmerge/dtoverlay.1

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
.TH DTOVERLAY 1
2+
.
3+
.SH NAME
4+
dtoverlay \- load a device-tree overlay
5+
.
6+
.
7+
.SH SYNOPSIS
8+
.SY dtoverlay
9+
.OP \-d dir
10+
.OP \-p string
11+
.OP \-v
12+
.OP \-D
13+
.OP \-r
14+
.OP \-R
15+
.OP \-l
16+
.OP \-a
17+
.RI [ overlay " [" param=val \|.\|.\|.]]
18+
.YS
19+
.
20+
.SY dtoverlay
21+
.B \-h
22+
.RI [ overlay " [" param ]]
23+
.YS
24+
.
25+
.
26+
.SH DESCRIPTION
27+
.B dtoverlay
28+
is a command line utility for manipulating the system's runtime device-tree by
29+
adding or removing overlays.
30+
It can also customize the base device-tree or overlays by setting parameters
31+
within them.
32+
See
33+
.B [DTREE]
34+
for more information.
35+
.
36+
.PP
37+
By default, without the
38+
.B -r
39+
or
40+
.B -R
41+
options, the application adds the specified overlay. Manipulation of
42+
active device-tree overlays usually requires root privileges.
43+
.
44+
.
45+
.SH OPTIONS
46+
.
47+
.TP
48+
.BR \-a
49+
Lists all defined device-tree overlays, placing a "*" next to those that are
50+
currently loaded.
51+
.
52+
.TP
53+
.BR \-d " \fIdir\fR"
54+
Specifies an alternate location path from which to load overlays. The utility
55+
defaults to "/boot/overlays" or "/flash/overlays".
56+
.
57+
.TP
58+
.BR \-D
59+
Dry-run; prepares the specified overlay but doesn't apply it. The resulting
60+
prepared overlay is saved as "dry-run.dtbo".
61+
.
62+
.TP
63+
.BR \-h [\fIoverlay\fR] [\fIparam\fR]
64+
If given without
65+
.I overlay
66+
or
67+
.I param
68+
displays help on the application overall. If
69+
.I overlay
70+
is specified, prints help on that overlay. Finally, if
71+
.I param
72+
is also specified, prints help on that parameter of the overlay. To query
73+
parameters on the base overlay, specify "dtparam" as the
74+
.IR overlay .
75+
.
76+
.TP
77+
.BR \-l
78+
Lists all currently loaded device-tree overlays, in the order they were loaded.
79+
This also specifies the index of each overlay.
80+
.
81+
.TP
82+
.BR \-p " \fIstring\fR"
83+
Override the platform's "compatible" string, normally read from
84+
"/proc/device-tree/compatible". This is used with the overlay map to determine
85+
which platform-specific overlay to read (if necessary).
86+
.
87+
.TP
88+
.BR \-r
89+
Remove overlay. With this option, the utility will remove the specified
90+
overlay. If no overlay is given, the last overlay loaded will be removed.
91+
Overlays can be specified by name or by index.
92+
.
93+
.TP
94+
.BR \-R
95+
Remove the specified overlay, and all subsequent overlays that were loaded
96+
after it. If no overlay is given, all overlays will be removed. Overlays can
97+
be specified by name or by index.
98+
.
99+
.TP
100+
.BR \-v
101+
Verbose operation; the utility will produce more output.
102+
.
103+
.
104+
.SH EXAMPLES
105+
.
106+
.TP
107+
.B sudo dtoverlay w1-gpio
108+
Load the w1-gpio overlay (to enable Dallas 1-Wire on GPIO4). Note that root
109+
privileges are usually required for manipulating the device-tree overlays
110+
(hence, sudo in the example).
111+
.
112+
.TP
113+
.B dtoverlay -l
114+
Show the loaded overlays.
115+
.
116+
.TP
117+
.B sudo dtoverlay -r
118+
Remove the last loaded overlay.
119+
.
120+
.TP
121+
.B sudo dtoverlay gpio-shutdown gpio_pin=7 active_low=0 gpio_pull=down
122+
Load the gpio-shutdown overlay specifying that it should pull GPIO7 down and
123+
monitor it for a rising edge to initiate shutdown.
124+
.
125+
.TP
126+
.B dtoverlay -h gpio-shutdown
127+
Display help for the gpio-shutdown overlay
128+
.
129+
.TP
130+
.B sudo dtoverlay -r gpio-shutdown
131+
Remove the gpio-shutdown overlay, wherever it is in the load order.
132+
.
133+
.
134+
.SH HOOKS
135+
.B dtoverlay
136+
attempts to call two executables (shell scripts by default) during its
137+
operation:
138+
.B dtoverlay-pre
139+
prior to making device-tree modifications, and
140+
.B dtoverlay-post
141+
afterwards. Each executable is optional and will be ignored if not present.
142+
.
143+
.
144+
.SH SEE ALSO
145+
.BR dtparam (1),
146+
.BR dtmerge (1),
147+
.B [DTREE]
148+
.
149+
.
150+
.SH REFERENCES
151+
.TP
152+
.B [DTREE]
153+
https://www.raspberrypi.org/documentation/configuration/device-tree.md

0 commit comments

Comments
 (0)