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
8in a manufacturing or field environment.
9
10If an OpenBMC implementation provides MinimumShipLevelRequired, it must be
11on `/xyz/openbmc_project/control/minimum_ship_level_required`.  There are
12**no** requirements on how the setting is used; implementations are free to
13react to the 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
22when a particular inventory object does or does not meet the minimum ship
23level.
24
25## Implementation Notes
26
27Consider a server platform with an MSL requirement that a fan control card is
28a certain revision, and if it is not, the server must not be allowed to
29boot, unless a user explicitly specifies otherwise.
30
31Phosphor OpenBMC provides a basic implementation of MinimumShipLevelRequired.
32It maintains a setting store and interface for the setting value.  This
33implementation is suitable for the hypothetical platform implementation
34requirements, allowing a user to toggle the setting back and forth.
35
36To enable verification that MSL has been satisfied, the hypothetical platform
37implementation would need to write an application that implements
38MeetsMinimumShipLevel on the inventory assets to be verified.  At present
39Phosphor OpenBMC does not provide any applications that do this.  If your
40application is general purpose and could meet the needs of others, consider
41contributing it to Phosphor OpenBMC.  A possible implementation for the
42hypothetical fan control card might be an application that validates a number
43of hwmon sensors exist and then sets the MinimumShipLevelRequired on the
44fan inventory object accordingly.
45
46Finally, the setting and the inventory assets must be compared and the server
47prevented from powering on.  This could be accomplished with a custom application
48or for simple logic, with
49[PDM](https://github.com/openbmc/phosphor-dbus-monitor) rules.
50