| /* |
| * BAL Programmers Guide - introduction |
| */ |
| |
| /** \mainpage BAL Public Interface Concept |
| |
| \section intro Introduction |
| This document describes the BAL user interface. The user interface is constructed from a |
| small set of public APIs and an objects model. |
| |
| The objects model is designed to manage different entities in the system, and enables a simple and intuitive |
| approach for managing line card. |
| |
| The API layer is designed to enable the management of line card containing muultiple MAC and SWITCH devices |
| and support any host application architecture. It includes a set of APIs to access the line card configuration and |
| asynchronous indications to send events to the host application. |
| |
| The API layer is part of the Broadcom® BAL SDK, which is provided as C source code, which is |
| independent of the CPU and operating system being used. |
| |
| \section object_model_table BAL Object Model |
| |
| The system is modeled as a set of managed objects. The term “object” here doesn’t imply any inheritance, it |
| means an entity that can be addressed individually and has a set of properties (attributes) and methods |
| (operations), for example, access_terminal, flow, etc. |
| |
| Each object can have multiple properties (aka attributes), whereas a property is an object parameter that can be set or |
| retrieved independently. |
| - A property is a simple type or a structure containing one or more fields, where fields can themselves be |
| structures |
| - Each property has a specific permission type, such as Read-Only (RO) and Read-Write (RW). |
| |
| Object properties are grouped into sections/management groups. The following sections can contain zero or |
| more properties: |
| - Key—Field(s) that uniquely identify the object instance (for example, subscriber_terminal key = {subs_id, intf_id}). |
| - Configuration |
| - Read-Write, Read-Only and Write-Only configuration properties |
| - Statistics |
| - Performance monitoring counters |
| - Debug counters |
| - Autonomous Indications |
| - Notifications that are generated asynchronously. |
| Indications can be either autonomous (such as alarms) or asynchronous responses to previously |
| submitted configuration change (for instance, subscriber_terminal admin_state=up request). |
| |
| \section object_model_prop Object and Properties Implementation |
| |
| \subsection object_model_structs Object Structures |
| |
| The main input parameter of all the APIs is an object structure, referred to as the Object Request Message. Each |
| object section has a different structure that includes a generic header, object key, and a specific section structure |
| according to the section type (for example, configuration, statics, etc). |
| - Generic header: A basic component of all the different section structures is the object generic header |
| \ref bcmbal_obj |
| |
| - The configuration structure bcmbal_xx_cfg contains: |
| - The generic header \ref bcmbal_cfg |
| - The object key, if any |
| - The structure bcmbal_xx_cfg_data, containing all object configuration properties |
| |
| - This statistics structure bcmbal_xx_stat contains: |
| - The generic header \ref bcmbal_stat |
| - The object key, if any |
| - The structure bcmbal_xx_stat_data, containing all the object statistics |
| |
| - The per-autonomous indication structure bcmbal_xx_auto_yy contains: |
| - The generic header \ref bcmbal_auto |
| - The autonomous message ID is stored in the subgroup field. |
| - The object key, if any |
| - The structure bcmbal_xx_auto_yy_data, containing all indication properties, if any |
| |
| \subsection object_model_init_macros Structure Initialization Macros |
| The following macros are used for initializing objects: |
| - \ref BCMBAL_CFG_INIT(cfg_msg, _object, _key) |
| - \ref BCMBAL_STAT_INIT(stat_msg, _object, _key) |
| |
| The macros perform the following tasks: |
| - Check that the structure matches the object section. |
| - Clear all control fields in the generic header \ref bcmbal_obj. |
| |
| \subsection object_model_prop_macros Property Presence Mask Manipulation Macros |
| The presence mask indicates which of the properties in the object structure need to be accessed (set/get, etc.) |
| The mask is a bit field, wherein each bit corresponds to a specific property. The following macros should be used |
| for setting the presence mask: |
| |
| - Set configuration parameter value:\n |
| \ref BCMBAL_CFG_PROP_SET(_msg, _object, _parm_name, _parm_value) |
| - Indicate that the property should be fetched by a bcmolt_cfg_get() request:\n |
| \ref BCMBAL_CFG_PROP_GET(_msg, _object, _parm_name) |
| - Indicate that the statistic should be fetched by a bcmolt_stat_get() request:\n |
| \ref BCMBAL_STAT_PROP_GET(_msg, _object, _parm_name) |
| |
| \subsection object_model_enums Enumerations |
| In the following descriptions, XX is the object name and YY is the property name from the XML model. |
| |
| The system model includes the enumerations: |
| - The bcmbal_obj_id enumeration lists all objects. It includes per-object BCMBAL_OBJ_ID_XX constants, |
| where XX is the object name from the XML model. |
| - The bcmbal_xx_cfg_id enumeration lists all XX objects' properties from the “Configuration” section in the |
| XML model. It includes the BCMBAL_XX_CFG_ID_YY constants. |
| - The bcmbal_xx_stat_id enumeration lists all XX object's properties from the “Statistics” section in the XML |
| model. It includes the BCMBAL_XX_STAT_ID_YY constants. |
| - The bcmbal_xx_auto_id enumeration lists all XX object's indications from the “Autonomous Indications” |
| section in the XML model. It includes the BCMBAL_XX_AUTO_ID_YY constants. |
| |
| \section api_section BAL Public API |
| See \ref api in API Reference chapter |
| */ |