Add HLD for H/W capabilities fields in platform.json #768
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| # Platform capability file enhancement # | ||
|
|
||
| ### Rev 0.1 | ||
|
|
||
| ## Table of Content | ||
|
|
||
| ## Revision | ||
|
|
||
| | Rev | Date | Author | Change Description | | ||
| |:---:|:-----------:|:----------------------------:|----------------------| | ||
| | 0.1 | | Arun Saravanan Balachandran | Initial version | | ||
|
|
||
| ## Scope | ||
|
|
||
| This document provides information on the enhancements for platform capability file `platform.json`. | ||
|
|
||
| ## Definitions/Abbreviations | ||
|
|
||
| | Definitions/Abbreviation | Description | | ||
| |--------------------------|-------------| | ||
| | BMC | Baseband Management Controller | | ||
| | NOS | Network Operating System | | ||
| | PSU | Power Supply Unit | | ||
|
|
||
| ## Overview | ||
|
|
||
| Each networking switch has a set of platform components (e.g: Fans, PSUs, LEDs, etc.) and these components in each platform can have different characteristics (like supported colors for a LED). In a given platform, the components could be controlled by a dedicated platform controller (like BMC) or the NOS running on the CPU is required to control it and in the former the control of the components from the NOS could be limited. | ||
|
|
||
| In SONiC the platform components' supported attributes are made available via Platform API, but certain platform specific capabilties for the components are not available for the applications. | ||
|
|
||
| This document provides the enhancement for `platform.json` to address the above issue. | ||
|
|
||
| ## Design | ||
|
|
||
| Currently, `platform.json` is used for providing the expected structure of the platform components and interface details for supporting dynamic port breakout. | ||
|
|
||
| ### Platform capabilities field | ||
|
|
||
| A new set of `capabilities` fields are introduced in platform.json, for providing platform specific capablities on control and characteristics of the components. | ||
|
|
||
| For each component's attribute, the defined `capabilities` fields are as follows: | ||
|
|
||
| - "controllable" : A boolean, 'true' if the given attribute can be controlled from the NOS, 'false' otherwise. | ||
|
|
||
| **Note:** If 'controllable' field is not specified, the default value is assumed to be 'true'. | ||
| - Attribute specific fields: | ||
| - status led - "color" - A list of the supported colors. | ||
| - speed | ||
| - "minimum" - Minimum recommended fan speed that can be set. | ||
|
There was a problem hiding this comment. Could you please elaborate on who will be the consumer of this info? Also as platform facts for the test cases? There was a problem hiding this comment. Currently, these fields would be used as platform facts for platform API test suite. There was a problem hiding this comment. Since platform daemons should be using the platform API, I think some of these things should just be taken care of by vendor-side logic. Like the fan speeds are completely handled by platform API instead of thermalctld. There was a problem hiding this comment. @zzhiyuan: I'm not sure I understand your comment. The main usage of these values is for testing purposes to understand boundaries when testing the device. Can you please elaborate? There was a problem hiding this comment. Ah, I meant more for the latter part, "these can also be consulted by any platform daemon before executing the respective APIs." Since there is already the fantray abstraction, I believe it is better for platform vendor to control the min/max fan speed which may differ by model, via thermal manager. Having values in platform.json for purpose of testing is fine. There was a problem hiding this comment. Ah. Yes, I agree with you. Platform daemons really shouldn't be referring to these values. |
||
| - "maximum" - Maximum recommended fan speed that can be set. | ||
|
|
||
| Sample `capabilities` fields: | ||
|
|
||
| ``` | ||
| { | ||
| "chassis": { | ||
| "name": "PLATFORM", | ||
| "status_led": { | ||
| "controllable": true, | ||
| "colors": ["off", "amber", "green"] | ||
| }, | ||
| "fan_drawers":[ | ||
| { | ||
| "name": "FanTray1", | ||
| "status_led": { | ||
| "controllable": true, | ||
| "colors": ["red", "green"] | ||
| } | ||
| "fans": [ | ||
| { | ||
| "name": "FanTray1-Fan", | ||
| "speed": { | ||
| "controllable": true, | ||
| "minimum": 40, | ||
| "maximum": 100 | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "name": "FanTray2", | ||
| "status_led": { | ||
| "controllable": true, | ||
| "colors": ["red", "green"] | ||
| } | ||
| "fans": [ | ||
| { | ||
| "name": "FanTray2-Fan", | ||
| "speed": { | ||
| "controllable": true, | ||
| "minimum": 40, | ||
| "maximum": 100 | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "psus": [ | ||
| { | ||
| "name": "PSU1", | ||
| "status_led": { | ||
| "controllable": false | ||
| } | ||
| "fans": [ | ||
| { | ||
| "name": "PSU1 Fan", | ||
| "speed": { | ||
| "controllable": false | ||
| } | ||
| } | ||
| ], | ||
| } | ||
| ], | ||
| "thermals": [ | ||
| { | ||
| "name": "Thermal 1", | ||
| "controllable": false | ||
| }, | ||
| { | ||
| "name": "Thermal 2", | ||
| "controllable": false | ||
| }, | ||
| ], | ||
|
|
||
| ... | ||
| } | ||
| ``` | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you elaborate in this context what controllable from the NOS mean? Most of these attributes would be managed by a daemon, either directly or via vendor code. So if say you change the fan speed, the thermalctld would change it back, and you'd have to stop the container in order to change it. Is this deemed controllable?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you maybe reword to:
- "controllable" : Boolean, 'true' if the given attribute can be controlled from the NOS, 'false' if it cannot. Defaults to 'true.'So you don't need the note below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If a given platform component can be controlled from the NOS (software-controlled), it is considered to be 'controllable' and if a platform component is controlled by a dedicated platform controller (like BMC) and is not controllable from the NOS running on the CPU, it is considered as 'not controllable'.