Updates

onlp/applications/apis.md

@@ -0,0 +1,17 @@
+# APIs
+
+## OID Specific APIs
+
+* [Chassis](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/chassis)
+* [Fan](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/fan)
+* [PSU](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/psu)
+* [Thermal](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/thermal)
+* [SFP](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/sfp)
+* [LED](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/led)
+* [Module](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/module)
+* [Generics](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/generic)
+* [Attributes](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/attributes)
+
+## System APIs
+* [Platform Management](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/platform)
+* [Debug](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/debug)

onlp/applications/attributes.md

@@ -0,0 +1 @@
+# Attributes

onlp/applications/chassis.md

@@ -0,0 +1,30 @@
+# Chassis
+
+## Chassis OID
+
+The Chassis OID represents the root OID for the entire system. There is only one Chassis OID and it is the only one guaranteed to exist at all times.
+The Chassis OID is represented by the special value ``ONLP_OID_CHASSIS``.
+
+## Chassis Information Structure
+
+Enumerating the current system topology starts with a call to ```onlp_chassis_info_get`` using the special value ONLP_OID_CHASSIS.
+This populates the ```onlp_chassis_info_t``` structure.
+
+There are no chassis-specific fields in this structure but it contains all of the top-level OIDs as its children. Those children can then be inspected and enumerated recursively.
+
+## Chassis Specific APIs
+
+### Chassis Environment
+
+The Chassis API provides a standard method to generate a JSON or YAML representation of the current environmental state of the system. This includes the health and status for all Fans, Thermals, and PSUs in the system. This provides the equivalent of ```show environment```.
+
+### Chassis Debug
+
+It is possible to query the Chassis for any generic debug, internal state or status for the purposes of technical support. The contents of this data are not interpreted or defined by the API itself but up to the system implementation.
+
+## Chassis Documentation
+
+* [Doxygen](https://htmlpreview.github.io/?https://raw.githubusercontent.com/opencomputeproject/OpenNetworkLinux/ONLPv2/packages/base/any/onlp/src/onlp/doc/html/group__oid-chassis.html)
+* [Header](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/chassis.h)
+
+[Return to APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/apis)

onlp/applications/concepts.md

@@ -1,3 +1,118 @@
 # ONLP API Concepts
 
 ## Overview
+
+The ONLP Application API manages the following types of platform objects:
+* SFPs
+* Fans
+* PSUs
+* Thermals Sensors
+* LEDs
+* Other Customized Platform Entities
+
+Platform objects in the ONLP API are represented as handles called Object IDs (OIDs). OIDs have both common and type-specific status, capabilities, and attributes.
+
+You interact with OIDs through two types of APIs -- one common to all OIDs and one specific to the type of OID.
+
+Attributes common to all OIDs represent status at a meta level. Is a thing present or missing? Is it operational or has it failed?
+
+Attributes specific to a particular type of OID represent that type's functionality. You can ask a Fan its current RPM but not an LED.
+
+There are functionality-specific APIs defined for each OID subtype.
+
+
+## OID Representation
+
+OIDs are just 32 bit integer handles. The most significant byte of the OID encodes the type (SFP, FAN, PSU, etc). The remaining 3 bytes are a unique id referencing a platform-defined object (like Fan 1, Fan 2, Fan 3, etc).
+The code that defines and manipulates OIDs can be found [here](https://github.com/opencomputeproject/OpenNetworkLinux/blob/ONLPv2/packages/base/any/onlp/src/onlp/module/inc/onlp/oids.h)
+
+
+## OID Relationships
+
+All OIDs have a parent OID. Some OIDs also have one or more child OIDs. This represents their current physical or logical relationship.
+
+For example, a PSU typically has both a Fan and a Thermal sensor built into it. The associated Fan and Thermal sensor for a given PSU are represented as OIDs that are children of the PSU.
+You can interrogate the Fan OID from the PSU using the normal Fan API, but the Fan itself cannot be accessed if the PSU is not also present.
+
+These parent/child relationships allow the user of the ONLP APIs to enumerate the system topolology as a directed acyclic graph at any given time.
+OID relationships can change over time -- perhaps you remove an existing PSU which contains a temperature sensor and replace it with a PSU that does not.
+
+
+## OID Interactions
+
+It must be possible to write an application which can operate on any ONLP enabled-hardware, regardless of the number and type of objects present
+on any given platform.
+
+Applications discover the OID topology by using the API to enumerate some or all of the current OID tree and interact with the discovered objects.
+
+The specific type of each OID (Fan, PSU, etc) is known at the time of discovery (see Representation above) and as such it can be submitted
+to the type-specific API for further programming.
+
+## Common OID Features
+
+In general all OID types have the following features exposed by their APIs.
+
+### The OID Header
+
+All OIDs support a common OID header structure (onlp_oid_hdr_t) which describes generic attributes for that object, such as:
+* The OID to which this structure belongs
+* The description of this object, such as
+  * "QSFP Thermal Sensor"
+  * "Fan Tray 4, Front Fan"
+* The parent of this OID
+
+Every class of OID has an accessor function to query that OID's header data in the form of:
+```
+int onlp_<type>_hdr_get(onlp_oid_t, onlp_oid_hdr_t*);
+```
+
+### The Information Structure
+
+All OIDs have an information structure that can be queried which provides the current status and capabilities of the object.
+This structure is defined in the form of:
+```
+typedef struct {
+        onlp_oid_hdr_t hdr;
+        /* Fields specific this particular type */
+} onlp_<type>_info_t;
+```
+
+This structure is queried through an API in the form us:
+```
+int onlp_<type>_info_get(onlp_oid_t, onlp_<type>_info_t*);
+```
+
+### JSON Representations
+
+All OID Information structures can be marshalled to/from JSON, either individually or recursively. All fields are preserved between C and JSON in the transaction.
+
+Information structures are converted to JSON through an API in the form of:
+```
+int onlp_<type>_info_to_json (onlp_<type>_info_t*, cJSON**, uint32_t flags);
+```
+
+Information structures are populated from JSON through an API in the form of:
+```
+int onlp_<type>_info_from_json (cJSON*, onlp_<type>_info_t*);
+```
+
+### User JSON Representations
+
+All OID Information structures can produce a "User" JSON representation which produces a version of the information suitable for communication to the system user.
+This representation takes into account the capabilities of the object as well as the valididity of the fields in the information structure.
+
+The regular JSON structure provides complete fidelity with the the C structure but obviously contains information specific to the APIs.
+
+The User JSON interprets the flags and capabilities and produces a human-readable format that defines what the status of the object is.
+This representation is used to communicate the status to the user.
+
+While the regular JSON interchange is lossless this version is not.
+
+Getting this representation is done thorough an API in the form of:
+```
+int onlp_<type>_info_to_user_json (onlp_<type>_info_t*, cJSON **, uint32_t flags);
+```
+
+There is no ```from_user_json``` as the representation is not sufficient to reconstruct the information structure.
+
+[Next: APIs](http://opencomputeproject.github.io/OpenNetworkLinux/onlp/applications/apis)

onlp/applications/debug.md

@@ -0,0 +1 @@
+# Debug

onlp/applications/fan.md

@@ -0,0 +1 @@
+# Fans

onlp/applications/generic.md

@@ -0,0 +1 @@
+# Generics

onlp/applications/led.md

@@ -0,0 +1 @@
+# LEDs

onlp/applications/module.md

@@ -0,0 +1 @@
+# Modules

onlp/applications/platform.md

@@ -0,0 +1 @@
+# Platform

onlp/applications/psu.md

@@ -0,0 +1 @@
+# PSUs

onlp/applications/sfp.md

@@ -0,0 +1 @@
+# SFPs

onlp/applications/thermal.md

@@ -0,0 +1 @@
+# Thermals