From 5d56594f1f126d8a31d072e1c987f2e5c2cdfb5c Mon Sep 17 00:00:00 2001 From: Jeffrey Townsend Date: Tue, 8 Jan 2019 20:02:12 -0800 Subject: [PATCH] Updates --- onlp/implementors/attributei.md | 19 +++++++++++ onlp/implementors/chassisi.md | 8 ++--- onlp/implementors/fani.md | 27 ++++++++++++++++ onlp/implementors/generici.md | 24 ++++++++++++++ onlp/implementors/ledi.md | 24 ++++++++++++++ onlp/implementors/modulei.md | 28 ++++++++++++++++ onlp/implementors/platformi.md | 57 +++++++++++++++++++++++++++++++++ onlp/implementors/psui.md | 29 +++++++++++++++++ onlp/implementors/sfpi.md | 28 ++++++++++++++++ onlp/implementors/thermali.md | 22 +++++++++++++ 10 files changed, 262 insertions(+), 4 deletions(-) diff --git a/onlp/implementors/attributei.md b/onlp/implementors/attributei.md index a9cfac10..d3d0ef1d 100644 --- a/onlp/implementors/attributei.md +++ b/onlp/implementors/attributei.md @@ -1,4 +1,23 @@ # attributei +The purpose of this module is to provide any standard and/or custom attributes for any OID. + +## Supporting Attributes + +In order to operate on an attribute your ```onlp_attributei_supported()``` function must return True for the named attribute on the given OID. +If it does not then ```onlp_attributei_get()``` and ```onlp_attributei_set()``` will not be called with that attribute name. + +## Standard Attributes + +While custom attributes are completely optional, it is required that at a very minimum the Chassis OID supports retreiving both the ONIE attribute and the Asset attribute using ```onlp_attributei_onie_info_get()``` and ```onlp_attributei_asset_info_get()```. + +Supporting these on anything other than the Chassis OID is optional. + +Should a FRU or Module support either of these attributes then you are encouraged to support them on those OIDs as well. + +## Attributei Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__attributei.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/attributei.h) + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/chassisi.md b/onlp/implementors/chassisi.md index 3ff98aa6..9407b93f 100644 --- a/onlp/implementors/chassisi.md +++ b/onlp/implementors/chassisi.md @@ -2,9 +2,9 @@ The purpose of this module is to implement platform properties of the Chassis OID. -There are only two functions which you must implement: +There is only one function you must implement: -### ```onlp_chassis_hdr_get()``` +## ```onlp_chassis_hdr_get()``` This returns the chassis root oid hdr for the system. @@ -12,10 +12,10 @@ You must mark the chassis oid status as both PRESENT and OPERATIONAL. You must return all top-level chassis OID children in the coids table. -### ```onlp_chassisi_info_get()``` +## ```onlp_chassisi_info_get()``` There are no fields currently defined in the ```onlp_chassis_info_t``` structure so it is currently equivalent to populating the OID header. -The current default implementation of ```onlp_chassisi_info_get()``` does this for you. +The current default implementation of ```onlp_chassisi_info_get()``` does this for you and there is no need to provide this function at this time. # Chassisi Documentation * [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__chassisi.html) diff --git a/onlp/implementors/fani.md b/onlp/implementors/fani.md index c3853083..49bb103f 100644 --- a/onlp/implementors/fani.md +++ b/onlp/implementors/fani.md @@ -1,4 +1,31 @@ # fani +The purpose of this module is to implement platform properties of the Fan OID. + +There are only two functions which you must implement: + +## ```onlp_fani_hdr_get()``` + +This returns the oid header for the given fan oid. + +* If the fan is present then you must set the PRESENT flag. Otherwise it is assumed to be absent and no further operations will be performed. +* If the fan is in a failure state then you must set the FAILED flag. If a fan has failed then no other operations will be performed. + +In the event that a fan or fan tray has a software visible child oid (like an LED) then those children must be populated in the coid table. + +## ```onlp_fani_info_get()``` + +This returns the full information structure for the fan. This includes the capability flags and current state of the variables corresponding to those capabilities (rpm, percentage, etc). + +## Fani Set Functions + +If the SET capability flags are set by ```onlp_fani_info_get()``` then the ```onlp_fani_*_set``` functions should be available and functional. +They will not be called unless the capabilities are reported. + +## Fani Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__fani.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/fani.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/fani.c) + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/generici.md b/onlp/implementors/generici.md index 0bd82ae6..cb76df81 100644 --- a/onlp/implementors/generici.md +++ b/onlp/implementors/generici.md @@ -1,5 +1,29 @@ # generici +The purpose of this module is to implement platform properties of the Generic OID. + +There is only one function you must implement: + +## ```onlp_generic_hdr_get()``` + +This returns the oid header for the given generic oid. + +* You must mark the OID as PRESENT. + +## ```onlp_generici_info_get()``` + +There are no fields currently defined in the ```onlp_generic_info_t``` structure so it is currently equivalent to populating the OID header. +The current default implementation of ```onlp_generic_info_get()``` does this for you and there is no need to provide this function at this time. + +## Notes + +While the Generic OID can be a parent container for other OIDs it is generally designed to be used as a handle in conjunction with the Attribute API to expose custom features. +There are no defined behaviors for the Generic OID. + +# Generici Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__generici.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/genericii.h) + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/ledi.md b/onlp/implementors/ledi.md index 21a654fc..d113d97e 100644 --- a/onlp/implementors/ledi.md +++ b/onlp/implementors/ledi.md @@ -1,4 +1,28 @@ # ledi +The purpose of this module is to implement platform properties of the Led OID. + +There are only two functions which you must implement: + +## ```onlp_ledi_hdr_get()``` + +This returns the oid header for the given led oid. + +* If the led is present then you must set the PRESENT flag. Otherwise it is assumed to be absent and no further operations will be performed. + +## ```onlp_ledi_info_get()``` + +This returns the full information structure for the led. This includes the capability flags and current mode of the LED if applicable. + +## Ledi Set Functions + +If the SET capability flags are set by ```onlp_ledi_info_get()``` then the ```onlp_ledi_*_set``` functions should be available and functional. +They will not be called unless the capabilities are reported. + +## Ledi Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__ledi.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/ledi.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/ledi.c) + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/modulei.md b/onlp/implementors/modulei.md index 91e32535..64ea9488 100644 --- a/onlp/implementors/modulei.md +++ b/onlp/implementors/modulei.md @@ -1,4 +1,32 @@ # modulei +The purpose of this module is to implement platform properties of the Module OID. + +There is only one function you must implement: + +## ```onlp_module_hdr_get()``` + +This returns the oid header for the given module oid. + +* You must mark the OID as PRESENT. +* If the module has failed or is inoperable you may set the FAILED state. + +## ```onlp_modulei_info_get()``` + +There are no fields currently defined in the ```onlp_module_info_t``` structure so it is currently equivalent to populating the OID header. +The current default implementation of ```onlp_module_info_get()``` does this for you and there is no need to provide this function at this time. + +## Notes + +The Module OID Type is defined to be a proper, dynamic container for other OIDs. It differs from the Generic OID in that it represents a physical module with a OID heirarchy. +Think linecard or module port chassis. + +Modules heirarchies are visible to the user. + +# Modulei Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__modulei.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/moduleii.h) + + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/platformi.md b/onlp/implementors/platformi.md index cad7c622..2103d1d6 100644 --- a/onlp/implementors/platformi.md +++ b/onlp/implementors/platformi.md @@ -1,4 +1,61 @@ # platformi +The purpose of this module is to implement some or all of the following: + +* Platform Identification and Assignment as per the [Getting Started](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/getting_started) section. +* Provide Management Hooks which manage the platform fans and status LEDs based on the platform thermal plan and current state of any FRUs + * Fans are adjusted according to airflow type and values of various thermal sensors + * LEDs states may be changed over time to indicate the operational state (or lackthereof) of certain FRUs, including but not limited to: + * PSU failed, unplugged, or missing + * Fan failed or missing +* Provide Debug Hooks into the platform internals (optional) + * Many platforms have CPLDs and FPGAs with useful register state that can be exposed during development or tech support. + + +## Fan Management + +The ```onlp_platformi_manage_fans()``` function must be implemented to read the current state of the thermals and set all fan speeds appropriately. +On most platforms this should also set all fans to max if any fan is in a failure state, regardless of the values of the thermals. + +Implementation of this algorithm is highly specific to your platform. This function will be called periodically by the platform management daemon. +While this function should be comprehensive in its inspection and reaction it should not block for a unreasonable amount of time. + +## LED Managmeent + +The ```onlp_platformi_manage_leds()``` function must be implemented to set the state of all LEDs in the system consistent with the current state of the FRUs, +as per the platform policy. + +Many platforms have a "health" LED which may be green when all fans and PSUs are operational, or Yellow if a single PSU has failed, etc. + +The LED policy is left to the platform implementor. This function will be called periodically by the platform management daemon. +It should not block for an unreasonable amount of time. + + +## Baseboard Management Controllers + +If your platform contains a BMC then the Fan and LED algorithms will be implemented there and not by ONLP. +In this case there is no need to implement the fan and led management routines. + +## Platformi Debug Hook + +The ```onlp_platformi_debug()``` function an ```argc``` and and ```argv``` and should return its output through the passed AIM PVS pointer. + +While an application can call this it is usually issue through the command line tools. + +For example, from the onlpd tool you might run: + +```#> onlpd debug cpld-dump 0 1 2``` + +In this case the parameters "cpld-dump", "0, "1", "2" will be passed to your ```onlp_platformi_debug()``` routine, the output collected, +and shown to the user. + +This interface is optional. + +## Platformi Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__platformi.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/platformi.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/platformi.c) + + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) \ No newline at end of file diff --git a/onlp/implementors/psui.md b/onlp/implementors/psui.md index 5d21682c..af920564 100644 --- a/onlp/implementors/psui.md +++ b/onlp/implementors/psui.md @@ -1,4 +1,33 @@ # psui +The purpose of this module is to implement platform properties of the PSU OID. + +There are only two functions which you must implement: + +## ```onlp_psui_hdr_get()``` + +This returns the oid header for the given PSU oid. + +* If the PSU is present then you must set the PRESENT flag. Otherwise it is assumed to be absent and no further operations will be performed. +* If the PSU is present but unplugged you must set the UNPLUGGED flag. No operations are attempting on an unplugged PSU. +* IF the PSU has failed then you must set the FAILED flag. No operations are performed on a failed PSU. + +If the PSU has Fan and or LED children they should be added to the coid table. + +## ```onlp_psui_info_get()``` + +This returns the full information structure for the PSU. This includes the capability flags and current values for all available fields: +* Power, Voltage, and Current - PIN, POUT, VIN, VOUT, IIN, IOUT (in milli-units) +* AC, DC12, or DC48 + +## PSU Set APIs + +There are no defined APIs for setting any PSU values. This may change in the future. + +## PSUi Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__psui.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/psui.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/psui.c) + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/sfpi.md b/onlp/implementors/sfpi.md index ab3f59a9..6c5a62a3 100644 --- a/onlp/implementors/sfpi.md +++ b/onlp/implementors/sfpi.md @@ -1,5 +1,33 @@ # sfpi +The purpose of this module is to implement platform properties of the SFP OID. + +## ```onlp_sfpi_hdr_get()``` + +You must implement this function. If an SFP is present then you must set the OID PRESENT status flag or no other operations will be performed. +It will be assumed that the SFP module is absent. + +## SFP Operations + +The sfpi interface is different from the other interfaces in that it synthesizes the contents of the ```onlp_sfp_info_t``` structure from the information provided by the SFPI interface. + +The MSA SFF decode for both identification and DOM information is parsed in the higher layers. Your SFPI interface need only provide the following: + +* SFP Presence Detection +* Reading SFP Signals + * RX_LOS +* Writing SFP Signals + * TX_DISABLE, LP_MODE, RESET, etc +* Generic Read/Write Access to the SFP via I2C + +## SFP Implementations + +Supporting all relevant SFP controls, status bitmaps, and read/write operations is required to provide rich access to all required SFP features. + +## SFPi Documentation +* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__sfpi.html) +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/sfpi.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/sfpi.c) --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis) diff --git a/onlp/implementors/thermali.md b/onlp/implementors/thermali.md index c4e8ce67..ed51d7c7 100644 --- a/onlp/implementors/thermali.md +++ b/onlp/implementors/thermali.md @@ -1,4 +1,26 @@ # thermali +The purpose of this module is to implement platform properties of the Thermal OID. + +There are only two functions which you must implement: + +## ```onlp_thermali_hdr_get()``` + +This returns the oid header for the given thermal oid. + +* These are not typically FRUs but the PRESENT status must still be set. Otherwise no other operations will be performed. +* If the sensor is failing then set the FAILED status. No operations will be performed on a failed sensors. + +## ```onlp_thermali_info_get()``` + +This returns the full information structure for the thermal sensor. This includes the capability flags and current state of the variables corresponding to those capabilities (rpm, percentage, etc). +In most cases this is just the current temperature (in millicelcius) but may include thermal warning and shutdown thresholds. + +## Thermali Documentation +* [Doxygen]() +* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/platformi/thermali.h) +* [Example Implementation](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/platforms/accton/x86-64/as7712-32x/onlp/builds/x86_64_accton_as7712_32x/module/src/thermali.c) + + --- [Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/implementors/apis)