OCAP Stack Host 2x SNMP MIBs Design by keralaguest

VIEWS: 79 PAGES: 11

									OCAP RI Stack Host 2.x SNMP MIBs Design

                               Version 1.0


                              July 12, 2011




 The information in this document is private data and company confidential.

                  EchoStar Technologies Corporation
     90 Inverness Circle East  P.O. Box 6552  Englewood, CO 80155
               Tel: (303) 706-5121  Fax: (303) 799-6222
OCAP RI Stack Host2x SNMP MIBs Design                                        Page 2


Revision History

      Date         Version                    Description         Author
                   Number
   May 20, 2010      0.1      Initial Draft                      Alan Cohn




                           Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                                                                     Page 3


Table of Contents

1. Introduction ..................................................................................................................... 4
2. References ....................................................................................................................... 4
3. Acronyms ........................................................................................................................ 4
4. General Software Requirements ..................................................................................... 5
5. Software Layer Interactions Involving MIB Resolutions .............................................. 6
6. SNMP Agent / Proxy Agent / OCAP Communication .................................................. 7
7. OCAP RI Stack Changes ................................................................................................ 7
8. OCAP MPE SNMP API Requirements .......................................................................... 8




                                        Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                 Page 4




1. Introduction

There are a number of OpenCable Host Device 2.X MIBs that require information from
the OCAP RI stack. This document describes the necessary changes to the OCAP RI
stack in order to implement the OpenCable Host Device 2.X MIB Specification for the
associated MIBs.


2. References

OC-SP-HOST2.1-CFR-I10-091211
OC-SP-MIB-HOST2.X-I09-091211
OpenCable Host Device 2.X Specification MIBs in OCAP stack:
ocStbHostJVMInfo,
      ocStbHostJVMHeapSize,
      ocStbHostJVMAvailHeap,
      ocStbHostJVMLiveObjects,
      ocStbHostJVMDeadObjects,
ocStbHostSoftwareApplicationInfoTable,
      ocStbHostSoftwareAppNameString,
      ocStbHostSoftwareAppVersionNumber,
      ocStbHostSoftwareStatus,
      ocStbHostSoftwareOrganizationId,
      ocStbHostSoftwareApplicationId,
      ocStbHostSoftwareApplicationSigStatus

3. Acronyms

JVM –         Java Virtual Machine
MIB –         Management Information Base
MPE –         Platform Independent portable C code
MPEOS –       OS Functionality Dependant C code
OID –         Object Identifier
OCAP –        OpenCable Application Platform
PDU –         Protocol Data Unit
SNMP –        Simple Network Management Protocol
UDP –         User Datagram Protocol




                         Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                     Page 5



4. General Software Requirements

There are a number of MIBs that require information from the OCAP stack as described
in the OpenCable Host Device 2.X MIB Specification. The OCAP stack must gather the
information on a timely base and cache the information in the MPE layer. Whenever a
SNMP request is received from a SNMP Manager for the MIB information, the cached
information in the MPE layer will be sent to the Manager. The cached information should
be in the format (integer or string) as expected by the MIB. The cached information
should also be protected (mutex) from dual access by the stack and the MPE layer. The
ocStbHostJVMLiveObjects and ocStbHostJVMDeadObjects MIBs require the OCAP
stack JVM provide internal JVM values.




                          Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                       Page 6


5. Software Layer Interactions Involving MIB Resolutions
The following diagram illustrates the boundaries between the main software layers for the
Cable Box.




The Driver layer provides the hardware abstraction/adaptation for the system; it is
hardware dependent. The MPEOS layer encapsulates the Driver implementation
providing a hardware independent abstraction to the MPE layer. The MPE layer has no
knowledge of the hardware used on the set-top box. The SNMP proxy is part of the
MPEOS layer as shown. The hatched region separates EchoStar implemented code and
the CableLabs Reference Implementation. This boundary comes into play when an
SNMP MIB request can only be handled by the OCAP layer. The requests involve JVM
(Java) related operational parameters that only MPE can resolve. The access to this



                           Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                    Page 7


information will be provided by a MPE API.


6. SNMP Agent / Proxy Agent / OCAP Communication

The EchoStar set-top box contains a SNMP Agent (Net-SNMP 5.0.9) that communicates
externally to SNMP Manager(s) and internally via UDP with the Proxy Agent for
ocStbHost related MIBs. That is, the main SNMP Agent passes all ocStbHost related
MIBs to the Proxy Agent and all other MIBs are handled by the SNMP Agent. The
Proxy Agent will make the necessary MPE and MPEOS API calls for the MIB
information. If the MIB is for OCAP stack information then the MPE APIs are called for
the cached information. Note that the OCAP RI stack MIB information flows one-way
from the stack to the MPE layer. No MIB information flows into the stack at this time.


7. OCAP RI Stack Changes

The following lists indicate the OCAP RI stack files that either changed or are new.

Existing stack files:
ocap/ri_stack/java/base.filelist
ocap/ri_stack/java/src/base/org/cablelabs/impl/manager/mgrmgr.properties
ocap/ri_stack/java/src/base/org/cablelabs/impl/manager/SNMPManager.java
ocap/ri_stack/java/src/base/org/cablelabs/impl/manager/snmp/SNMPManagerImpl.java
ocap/ri_stack/java/javah.xml (autogenerated -> file
org_cablelabs_impl_manager_snmp_SNMPManagerImpl.h)
ocap/ri_stack/jni/src/Makefile
ocap/ri_stack/mpe/Makefile
ocap/ri_stack/java/src/base/org/cablelabs/impl/manager/application/AttributesImpl.java
ocap/ri_stack/java/src/base/org/cablelabs/impl/ocap/OcapMain.java

New stack files:
ocap/ri_stack/java/src/base/org/cablelabs/impl/manager/snmp/SnmpAppsDatabaseMonito
r.java
ocap/ri_stack/jni/src/base/org_cablelabs_impl_manager_snmp_SNMPManagerImpl.c
ocap/ri_stack/mpe/mgr/snmpmgr/snmpMgr.c
ocap/ri_stack/mpe/include/snmpMgr.h




                           Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                    Page 8



8. OCAP MPE SNMP API Requirements1

The proxy agent requires access to OCAP/JAVA information. This information will be
retrieved from MPE using the following two APIs.



         int get_ocap_mib_info_int(
                   E_OCAP_MIB_REQ_VALUES                   table,
                   E_OCAP_MIB_REQ_VALUES                   attribute,
                   unsigned int32                          row,
                   int                                     *returned_value );

         int get_ocap_mib_info_str(
                   E_OCAP_MIB_REQ_VALUES                   table,
                   E_OCAP_MIB_REQ_VALUES                   attribute,
                   unsigned int32                          row,
                   char                                    *returned_value );


SNMP data is either an integer or a character string. Having two functions makes this
precisely clear (argument types are statically known at compile time.) These functions
are overloaded to handle both single value and table value requests.




1
    OC-SP-MIB-HOST2.X-I09-091211   OpenCable Host Device 2.X Specification



                            Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                            Page 9


Since only an integer or a string will be returned, the functions return value will either be:

1)      0 interpreted as "no such oid exists."
2)      1 get_ocap_mib_info_int(): success
3)       n get_ocap_mib_info_str(): length of string returned
           from 1 … OCAP_MIB_REQ_MAX_BUFF_LEN – 1


Arguments:
     table: specifies the table whose value is requested

       attribute: if this is a table request then attribute is the item in the row requested,
otherwise it is ignored

       row: if this is a table request, then row is the index into the table requested,
otherwise it is ignored. Index is 0 base.

        returned_value: pointer to local buffer to be filled in by the API. This pointer
will point to an integer variable or to a character buffer of length
OCAP_MIB_REQ_MAX_BUFF_LEN.

The API header file will contain the following constant and enumeration type. The
declarations of the functions discussed previously will be included as well. No other
header file will be included within this header file.

#define OCAP_MIB_REQ_MAX_BUFF_LEN 256
typedef enum
{
   OCAP_INVALID_ENUM = 0,

     OCAP_NOT_A_TABLE,
     HSAPPINFOTABLE,

     HSAPPNAMESTRING,
     HSAPPVERSIONNUMBER,
     HSSTATUS,
     HSORGID,
     HSAPPID,
     HSSIGSTATUS,

   HJVMHEAPSIZE,
   HJVMAVAILHEAP,
   HJVMLIVEOBJECTS,
   HJVMDEADOBJECTS,
   OCAP_MAX_ENUM
}E_OCAP_MIB_REQ_VALUES;




                            Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                                      Page 10


Below is an enum for returned values for non-table requests.
typedef enum
{
   MIB_GET_ERROR   = 0,
   MIB_GET_SUCCESS = 1
}E_OCAP_MIB_REQ_STATUS;

Only one table MIB is in this enumeration. The attribute enumerations are also included
for clarity and brevity. The indented enumeration values are the attributes of the table
enumeration preceding them. This strategy ensures that every value passed into the APIs
is unique.


Detailed enumeration descriptions:

 HSAPPINFOTABLE : ocStbHostSoftwareApplicationInfoTable
      "This table allows the manager to display and retrieve
        self-diagnostic software information of all available
        applications."
 This value is used in the table parameter for the following attribute parameters.

 HSAPPNAMESTRING: ocStbHostSoftwareAppNameString
    "The applications name string."

 HSAPPVERSIONNUMBER: ocStbHostSoftwareAppVersionNumber
    "The applications version number."

 HSSTATUS: ocStbHostSoftwareStatus
     "The software status of the application."

 HSORGID: ocStbHostSoftwareApplicationId
 "Organization ID captured in the XAIT or AIT."

 HSAPPID: ocStbHostSoftwareApplicationId
 "This 16 bit field uniquely identifies the
        application function as assigned by the
        responsible/owning organization identified in
        ocStbHostSoftwareOrganizationId."

 HSSEGSTATUS: ocStbHostSoftwareApplicationSigStatus
 "The field SHALL be set to “Okay” if
        the XAIT has been read successfully
        or “Error” if there was an error reading
        the table (e.g., CRC error)."




                           Private Data - Company Confidential
OCAP RI Stack Host2x SNMP MIBs Design                                          Page 11


The OCAP_NOT_A_TABLE value is used for the table parameter for the following
attribute parameters.


 HJVMHEAPSIZE: ocStbHostJVMHeapSize
    "The total amount of DRAM allocated to the Java Virtual
      Machine heap. The units are kilobytes, defined to be
      1,024 bytes."

HJVMAVAILHEAP: ocStbHostJVMAvailHeap
    "The amount of DRAM in the Java Virtual Machine heap that
      is not allocated and is available for use.
      The units are kilobytes, defined to be 1,024 bytes."

 HJVMLIVEOBJECTS: ocStbHostJVMLiveObjects
    "The number of active object instances in the Java Virtual
      Machine that are reachable from running code."

 HJVMDEADOBJECTS: ocStbHostJVMDeadObjects
    "The number of object instances in the Java Virtual Machine
      that are NOT reachable from running Code."




                         Private Data - Company Confidential

								
To top