README.msl.md
1# Minimum Ship Level (MSL)
2
3## Overview
4
5The OpenBMC API provides a global setting for enforcement of minimum ship level.
6Typically a setting like this would be used to enable the use of hardware
7configurations in platform development that may not necessarily be supported in
8a manufacturing or field environment.
9
10If an OpenBMC implementation provides MinimumShipLevelRequired, it must be on
11`/xyz/openbmc_project/control/minimum_ship_level_required`. There are **no**
12requirements on how the setting is used; implementations are free to react to
13the value of the setting however they choose.
14
15In anticipation of a common use case of examining hardware assets, determining
16if they are of a certain revision or part, and taking some action if they are
17not, the OpenBMC API also provides an inventory decorator called
18MeetsMinimumShipLevel.
19
20MeetsMinimumShipLevel can be implemented on any object in the inventory
21namespace. Again, there are no requirements on what an implementation does when
22a particular inventory object does or does not meet the minimum ship level.
23
24## Implementation Notes
25
26Consider a server platform with an MSL requirement that a fan control card is a
27certain revision, and if it is not, the server must not be allowed to boot,
28unless a user explicitly specifies otherwise.
29
30Phosphor OpenBMC provides a basic implementation of MinimumShipLevelRequired. It
31maintains a setting store and interface for the setting value. This
32implementation is suitable for the hypothetical platform implementation
33requirements, allowing a user to toggle the setting back and forth.
34
35To enable verification that MSL has been satisfied, the hypothetical platform
36implementation would need to write an application that implements
37MeetsMinimumShipLevel on the inventory assets to be verified. At present
38Phosphor OpenBMC does not provide any applications that do this. If your
39application is general purpose and could meet the needs of others, consider
40contributing it to Phosphor OpenBMC. A possible implementation for the
41hypothetical fan control card might be an application that validates a number of
42hwmon sensors exist and then sets the MinimumShipLevelRequired on the fan
43inventory object accordingly.
44
45Finally, the setting and the inventory assets must be compared and the server
46prevented from powering on. This could be accomplished with a custom application
47or for simple logic, with
48[PDM](https://github.com/openbmc/phosphor-dbus-monitor) rules.
49