10  YControl Subsystem

The YControl subsystem is used to allow asynchronous operation between netconfd-pro and higher layer services, such as SIL-SA.  The YControl subsystem is a shared library that is linked with other libraries and runs in the vendor process.

The YControl subsystem is designed to support multiple independent upper-layer services . The main server does not provide an external API to the server handler for each subsystem at this time.

An IO poll API is called periodically by the vendor process to check for incoming messages.

The subsystem provides a communication service between the server and another process. It does not provide any high-level service within the server. It handles the following services:

                   
                                          Vendor Process

 

 

 

 

 

 

 

 

 

 

 

 

Subsystem Software Components

Image1


Server to Subsystem Service Layer

 

 

10.1  YControl API Functions

 

Each high level service must register the proper callback functions with the YControl subsystem.

The application will poll the IO function periodically to handle communication with the main server. The callback functions registers with the subsystem will be invoked as needed, based on the received message.

The main YControl functions are described in this section.

10.1.1  Initialization and Cleanup

The following functions are used for initialization and cleanup of the YControl subsystem:

 

 

 

/********************************************************************

* FUNCTION ycontrol_init

*

* Setup global vars before accepting any requests

*

* INPUTS:

*    argc == argument count

*     argv == argument array

*    subsys_id == sub-system identifier

* RETURNS:

*    status: 0 == OK

*********************************************************************/

extern status_t

    ycontrol_init (int argc,

                   char *argv[],

                   const xmlChar *subsys_id);

 

 

/********************************************************************

* FUNCTION ycontrol_init2

*

* Setup connection to server

*

* RETURNS:

*    status

*********************************************************************/

extern status_t

    ycontrol_init2 (void);

 

 

 

/********************************************************************

* FUNCTION ycontrol_register_service

*

* Register a specific service with the YumaPro control message manager

*

* INPUTS:

*

* RETURNS:

*    status

*********************************************************************/

extern status_t

    ycontrol_register_service (const xmlChar *service_name,

                               ycontrol_service_start_t service_start,

                               ycontrol_service_stop_t service_stop,

                               ycontrol_service_msg_rcvr_t service_rcvr,

                               ycontrol_service_shutdown_t service_shut);

 

 

 

/********************************************************************

* FUNCTION ycontrol_cleanup

*

* Cleanup ycontrol layer

*

* INPUTS:

*   profile == service profile to cleanup

*

*********************************************************************/

extern void

    ycontrol_cleanup (void);

 

 

/********************************************************************

* FUNCTION ycontrol_request_shutdown

*

* Request a control message handler shutdown

*

*********************************************************************/

extern void

    ycontrol_request_shutdown (void);

 

 

/********************************************************************

* FUNCTION ycontrol_shutdown_requested

*

* Check if a control message handler shutdown is in progress

*

* RETURNS:

*    TRUE if shutdown mode has been started

*

*********************************************************************/

extern boolean

    ycontrol_shutdown_requested (void);

 

 

10.1.2  Runtime Functions

The following functions are used after initialization is complete to access the YControl subsystem:

 

 

 

/********************************************************************

* FUNCTION ycontrol_check_io

*

* Check for input/output

*

* RETURNS:

*   status

*********************************************************************/

extern status_t

    ycontrol_check_io (void);

 

 

/********************************************************************

* FUNCTION ycontrol_is_ready

*

* Check if the ycontrol ready is up and ready to be used

*

* RETURNS:

*   TRUE if ready; FALSE if not

*********************************************************************/

extern boolean

    ycontrol_is_ready (void);

 

 

 

/********************************************************************

* FUNCTION ycontrol_send

*

* Send a YControl message

*

* INPUTS:

*   service_id == service sending this message

*   msgid == address of message ID;

*       for response this is non-zero

*   msgtype == type of YControl message to send

*   service_payload == val_value_t tree to add to message payload

*                   == NULL if not used

*    msg_status == NO_ERR or error status for message; ignored if

*        service_payload is non-NULL

* OUTPUTS:

*   if *msgid was zero on input:

*       *msgid set to the message ID assigned to the msg

* RETURNS:

*   status

*********************************************************************/

extern status_t

    ycontrol_send (const xmlChar *service_id,

                   uint32 *msgid,

                   ycontrol_msgtype_t msgtype,

                   val_value_t *service_payload,

                   status_t msg_status);

 

 

/********************************************************************

* FUNCTION ycontrol_send_error

*

* Send a YControl <error> message

*

* INPUTS:

*   service_id == service sending this message

*   msgid == address of message ID;

*       for response this is non-zero

*   msg_status == NO_ERR or error status for message; ignored if

*        service_payload is non-NULL

*   error_index == error index if sending an <error> response

*   error_msg == error message if sending an <error> response

* RETURNS:

*   status

*********************************************************************/

extern status_t

    ycontrol_send_error (const xmlChar *service_id,

                         uint32 *msgid,

                         status_t msg_status,

                         uint32 error_index,

                         const xmlChar *error_message);

 

 

 

 

 

10.2  YControl Message Structure

Image2

 

There are 6 types of messages supported, indicated by the message-type leaf

 

 

Each message type shares the same payload structure. There are 3 formats, specified by the message-payload choice-stmt in the YANG module.'

 

 

 

10.2.1  yumaworks-ycontrol YANG Module

The yumaworks-ycontrol YANG module contains the YControl message structure.

 

 

module yumaworks-ycontrol {

 

    namespace "http://yumaworks.com/ns/yumaworks-ycontrol";

 

    prefix "yctl";

 

    import yuma-ncx { prefix ncx; }

    import yuma-types { prefix yt; }

 

    organization "YumaWorks, Inc.";

 

    contact

        "Support <support at yumaworks.com>";

 

    description

       "YumaPro control system message definition.";

 

    revision 2014-11-19 {

        description

          "Support '*' as the service-id to indicate a server

           event message that is intended for the YControl layer

           itself, called ALL_SERVICES.

           Add shutdown-event message for ALL_SERVICES";

    }

 

    revision 2014-04-08 {

        description

          "Initial version.";

    }

 

    container ycontrol {

      ncx:abstract;

      ncx:hidden;

 

      leaf message-id {

        mandatory true;

        type uint32 {

          range "1 .. max";

        }

        description

          "Message identifier.

           For server-response and subsys-response message types,

           this value is the same as the corresponding request

           message.";

      }

 

      leaf message-type {

        mandatory true;

        type enumeration {

          enum server-event {

            description

              "Message from server to sub-system.

               No response expected.";

          }

          enum server-request {

            description

              "Request message from server to sub-system.

               A response is expected.";

          }

          enum server-response {

            description

              "Response message from server to sub-system.

               Sent when subsys-req received.

               No response is expected";

          }

          enum subsys-event {

            description

              "Message from sub-system to server.

               No response expected.";

          }

          enum subsys-request {

            description

              "Request message from sub-system to server.

               A response is expected.";

          }

          enum subsys-response {

            description

              "Response message from sub-system to server.

               Sent when server-req received.

               No response is expected";

          }

          enum ycontrol-error {

            description

              "Response message from either sub-system or server.

               Sent when a recoverable YControl or service layer

               error occurs.

 

               If non-recoverable error, then session is dropped

               and no response is sent. Example error: message

               is for a service-id that does not exist.

               No response is expected";

          }

 

        }

        description "Message type";

      }

 

      leaf server-id {

        mandatory true;

        type union {

          type yt:NcxName;

          type string { length 0; }

        }

        description "Server identifier or empty if not known by subsys";

      }

 

      leaf subsys-id {

        mandatory true;

        type yt:NcxName;

        description "Subsystem identifier";

      }

 

      leaf service-id {

        mandatory true;

        type union {

          type yt:NcxName;

          type string {

            pattern '\*';

          }

        }

        description

          "Service identifier. The value '*' indicates a

           server-event message to all services. These messages

           are handled by the ycontrol library, not the individual

           service libraries.";

      }

 

      choice message-payload {

        mandatory true;

        container payload {

          description

            "This <payload> container is augmented with a

             service-specific container from other modules.";

 

          leaf shutdown-event {

            type empty;

            description

             "Message type: server-event;

              Purpose: The server is shutting down. Sent to

              all services (service-id = '*')

 

              Expected Response Message: none";

          }  // leaf shutdown-event

        }

        leaf ok {

          type empty;

          description

            "Sent when a request message is processed

             successfully and no data is needed in the

             response.";

        }

        container error {

          leaf error-number {

            mandatory true;

            type uint32;

            description "Internal error number";

          }

 

          leaf transaction-id {

            type string;

              description

                "Server specific transaction identifier.

                 Sent from subsystem to server in

                 subsys-response.

                 It identifies the transaction in case multiple

                 transactions are in progress at once.";

          }

 

          leaf error-message {

            type string;

            description

              "Internal error message, if different from

               get_error_string(error-number).";

          }

 

          leaf error-index {

            type uint32 {

              range "1 .. max";

            }

            description

              "Internal edit index number from <start-transaction>

               message. Set only if an edit-specific error occurred.";

          }

 

        }

 

      }  // choice message-payload

 

    }  // container ycontrol

 

}