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