docs/architecture/openbmc-systemd.md

5 which processes are started. There is a lot of documentation on systemd and to
9 [Unit](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#) -
11 [Service](https://www.freedesktop.org/software/systemd/man/systemd.service.html) -
13 [Target](https://www.freedesktop.org/software/systemd/man/systemd.target.html) -
19 On an OpenBMC system, you can go to /lib/systemd/system/ and see all of the
20 systemd units on the system. You can easily cat these files to start looking at
27 ---
29 ## Initial Power
31 When an OpenBMC system first has power applied, it starts the "default.target"
32 unless an alternate target is specified on the kernel command line. In Phosphor
33 OpenBMC, there is a link from `default.target` to `multi-user.target`.
35 You'll find all the phosphor services associated with `multi-user.target`.
37 ## Server Power On
40 [obmc-host-start@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_file…
43 To start it you would run `systemctl start obmc-host-start@0.target`.
49 ls -1 /lib/systemd/system/obmc-host-start@0.target.requires/
50 obmc-host-startmin@0.target
51 phosphor-reset-host-reboot-attempts@0.service
55 [obmc-host-startmin@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_f…
58 host-start and a host-startmin target allows the user to put services in the
59 `obmc-host-start@.target` that should only be run on an initial host boot (and
60 not run on host reboots). For example, in the output above you can see the user
61 only wants to run the `phosphor-reset-host-reboot-attempts@0.service` on a fresh
64 Next if we look at the `obmc-host-startmin@0.target`, we see this:
67 ls -1 /lib/systemd/system/obmc-host-startmin@0.target.requires/
68 obmc-chassis-poweron@0.target
72 You can see within `obmc-host-startmin@0.target` that we have another target in
73 there, `obmc-chassis-poweron@0.target`, along with a service aptly named
76 The `obmc-chassis-poweron@0.target` has corresponding services associated with
80 ls -1 /lib/systemd/system/obmc-chassis-poweron@0.target.requires/
81 op-power-start@0.service
82 op-wait-power-on@0.service
85 If you run `systemctl start obmc-host-start@0.target` then systemd will start
89 service (for example, the op-power-start.service will run prior to the
90 op-wait-power-on.service). These dependencies are set using targets and the
93 ## Server Power Off (Soft)
95 The soft server power off function is encapsulated in the
96 `obmc-host-shutdown@.target`. This target is soft in that it notifies the host
97 of the power off request and gives it a certain amount of time to shut itself
100 ## Server Power Off (Hard)
102 The hard server power off is encapsulated in the
103 `obmc-chassis-hard-poweroff@.target`. This target will force the stopping of the
104 soft power off service if running, and immediately cut power to the system.
108 The reboot of the server is encapsulated in the `obmc-host-reboot@.target`. This
109 target will utilize the soft power off target and then, once that completes,
110 start the host power on target.
114 The `obmc-host-quiesce@.target` is utilized in host error scenarios. When the
115 `obmc-host-quiesce@0.target` is entered, it puts the host state D-Bus
116 [object](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/S…
119 ## Server Emergency Power Off due to Error
121 The `obmc-chassis-emergency-poweroff@.target` is a wrapper target around the
122 `obmc-chassis-hard-poweroff@.target` and `obmc-host-quiesce@.target`. It is
123 utilized by applications that have detected critical thermal or power errors
125 and put the host into Quiesce (if the host is running). Certain non-critical
131 power on if they wished or a host stop / power off if they wanted to get out of
139 [state](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/St…
140 interfaces for more information on this function.
142 For example, if you wanted to execute the server power on function, you would do
145 > busctl set-property xyz.openbmc_project.State.Host
147 > RequestedHostTransition s xyz.openbmc_project.State.Host.Transition.On
149 Underneath the covers, this is calling systemd with the server power on target.
155 by systemd services or by monitoring for the appropriate D-Bus signal indicating
160 - If your application logic depends on other systemd based services then make it
162 - If other applications depend on your application logic then it should be a
164 - If your application failing during the target start could impact targets or
183 - If the service is a "oneshot" type, and the service is required (not wanted)
184   by the target then the target will fail if the service fails - Define a
187 - If the service is not a "oneshot", then it can not fail the target (the target
188   only knows that it started successfully) - Define a behavior for when the
189   service fails (OnFailure) option. - The service can not have
191   service is stopped (instead of when it fails) - \*See more information below
192   on [RemainAfterExit](#RemainAfterExit)
197 - The service which detects this failure is responsible for logging the
207 power, `obmc-chassis-poweron@0.target`, will have a
208 `OnFailure=obmc-chassis-poweroff@%i.target` error path. That is, if the chassis
209 power on target fails then power off the chassis.
214 - All targets should have a `OnFailure=obmc-quiesce-host@.target`
215 - All services which are required for a target to achieve its function should be
217 - All services should first try to be "Type=oneshot" so that we can just rely on
219 - If a service can not be "Type=oneshot", then it needs to have a
220   `OnFailure=obmc-quiesce-host@.target` and ideally set "RemainAfterExit=no"
221   (but see caveats on this below)
222 - If a service can not be any of these then it's up to the service application
223   to call systemd with the `obmc-quiesce-host@.target` on failures
231 `obmc-chassis-poweron@.target` twice. If you execute it when the operating
233 re-executed, you're going to crash your system. Given this info, the goal should
239 dependencies (systemd-analyze) but due to the complexity of our design, they do
242 For now, document the current dependencies on a witherspoon system for
254 ### Soft Power Off
257 obmc-host-shutdown.target
259      W: obmc-host-stopping.target (S)
260      B: obmc-host-stopping.target (S)
261   R: obmc-chassis-poweroff.target
262      R: obmc-host-stop.target
263         R: op-occ-disable.service
264            B: obmc-host-stop-pre.target
265      R: op-power-stop.service
266         W: obmc-power-stop.target (S)
267         B: obmc-power-stop.target (S)
268         W: obmc-power-stop-pre.target (S)
269         A: obmc-power-stop-pre.target (S)
270         W: mapper-wait@-org-openbmc-control-power.service
271         A: mapper-wait@-org-openbmc-control-power.service
272      R: op-wait-power-off.service
273         B: obmc-power-off.target (S)
274         W: obmc-power-stop.target (S)
275         B: obmc-power-stop.target (S)
276         W: obmc-power-stop-pre.target (S)
277         A: obmc-power-stop-pre.target (S)
278         W: mapper-wait@-org-openbmc-control-power.service
279         A: mapper-wait@-org-openbmc-control-power.service
280      R: op-powered-off.service
281         A: op-wait-power-off.service
282         R: op-wait-power-off.service
283         S: obmc-chassis-powered-off.target
284      W: pcie-poweroff.service
285         B: op-power-stop.service
286         A: obmc-power-stop-pre@.target
292 obmc-power-stop.target
293   W: obmc-power-stop-pre.target
294   A: obmc-power-stop-pre.target
296 obmc-power-stop-pre.target
297   W: obmc-host-stopped.target
298   A: obmc-host-stopped.target
300 obmc-host-stopped.target
301   W: obmc-host-stopping.target
302   A: obmc-host-stopping.target
303   B: obmc-power-stop-pre.target
305 obmc-host-stopping.target
306   W: obmc-host-stop-pre.target
307   A: obmc-host-stop-pre.target
308   B: obmc-host-stopped.target
310 obmc-host-stop-pre.target
311   B: obmc-host-stopping.target