YControl Subsystem

A subsystem application consists of a YControl subsystem and one or more upper-layer services. Only the SIL-SA Subsystem and DB-API Subsystem are supported at this time.

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

The YControl subsystem is designed to support multiple independent upper-layer services . The main server does not provide API support for custom service layers at this time.

Note

  • The YControl library supports only one subsystem at a time.

    • A subsystem can support one 'sil-sa' service and/or one 'db-api' service.

  • Only one subsystem can be registered with the server.

    • E.g., subsys-id subsys1 and subsys2 cannot both use the same subsystem application.

  • Multiple subsystem applications must be used instead.

    • E.g., --subsys-id=subsys1 is used in one application and --subsys-id=subsys2 is used in a separate application.

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:

  • connection and reconnection to the netconfd-pro server

  • configurable connect and retry parameters

  • the server can boot before or after the process using YControl.

  • registration API for higher layer services

  • message processing API for higher layer services

Subsystem Software Components

../_images/ycontrol_block_diagram.png

Server to Subsystem Service Layer

../_images/async_control_plane.png

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.

The following sample applications show how to use YControl API functions.

  • combo-app

  • db-api-app

  • sil-sa-app

  • py-sil-app

Initialization and Cleanup

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

  • ycontrol_init: Phase 1 Initialization

  • ycontrol_init2: Phase 2 Initialization

  • ycontrol_register_service: Register a set of callback functions fort a high-level service

  • ycontrol_cleanup: Shutdown YControl subsystem and all upper layer services

  • ycontrol_request_shutdown: Trigger shutdown of YControl subsystem and all upper layer services

  • ycontrol_shutdown_requested: Check if shutdown of YControl subsystem has been triggered

status_t ycontrol_init(int argc, char *argv[], const xmlChar *subsys_id)
status_t ycontrol_init2(void)
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)
void ycontrol_cleanup(void)
void ycontrol_request_shutdown(void)

Request a control message handler shutdown.

This is the correct way to shutdown YControl from the application.

boolean ycontrol_shutdown_requested(void)

Check if a control message handler shutdown is in progress.

Returns:

TRUE if shutdown mode has been started

Runtime Functions

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

  • ycontrol_check_io: Check for any incoming messages from the main server

  • ycontrol_is_ready: Make sure the YControl subsystem is ready for a new request

  • ycontrol_send: Send any YControl message to the main server

  • ycontrol_send_error: Send an error response to the main server

status_t ycontrol_check_io(void)
boolean ycontrol_is_ready(void)
status_t ycontrol_send(const xmlChar *service_id, uint32 *msgid, ycontrol_msgtype_t msgtype, val_value_t *service_payload, status_t msg_status)
status_t ycontrol_send_error(const xmlChar *service_id, uint32 *msgid, status_t msg_status, uint32 error_index, const xmlChar *error_message, const xmlChar *txid_str)

Send a YControl <error> message.

Parameters:

  • 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_message -- error message if sending an <error> response

  • txid_str -- transaction-id string to add (may be NULL to skip)

Returns:

status

YControl Message Structure

../_images/ycontrol_messages.png

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

  • server-request: request from server to subsystem, expecting a subsys-response

  • server-response: response from server to subsystem to a subsys-request message

  • server-event: event from server to subsystem; no response

  • subsys-request: request from subsystem to server, expecting a server-response

  • subsys-response: response from subsystem to server to a server-request message

  • subsys-event: event from subsystem to server; no response

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

  • container payload: message body

  • leaf ok: NO_ERR response

  • container error: error response

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