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)

Initialize the YControl library.

Setup global vars before accepting any requests. Process all the CLI parameters. There is no .conf file for a subsystem.

Parameters:

  • argc -- argument count

  • argv -- argument array

  • subsys_id -- sub-system identifier

Returns:

status: 0 OK

status_t ycontrol_init2(void)

Phase 2 initialization.

Setup connection to server.

Returns:

status

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)

Register a specific service with the YumaPro control message manager.

Officially only YumaPro services are supported but the YControl layer does not check. All callback functions must be provided . Only the receiver callback is technically required to do anything. It MUST send a subsys-response if a server-request is received.

Parameters:

  • service_name -- unique name of the service

  • service_start -- service start callback

  • service_stop -- service stop callback

  • service_rcvr -- Message receiver callback

  • service_shut -- service shutdown callback

Returns:

status

void ycontrol_cleanup(void)

Cleanup ycontrol layer.

Called by the application to cleanup resources. Must call if ycontrol_init function variant called.

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)

Check for input/output.

Called from application to process any incoming YControl messages.

Returns:

status

boolean ycontrol_is_ready(void)

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

Returns:

TRUE if ready; FALSE if not

status_t ycontrol_send(const xmlChar *service_id, uint32 *msgid, ycontrol_msgtype_t msgtype, val_value_t *service_payload, status_t msg_status)

Send a YControl message.

Parameters:

  • service_id -- service sending this message

  • msgid -- [out]

    address of message ID; for response this is non-zero

    *msgid set to the message ID assigned to the msg, if msgid non-NULL

  • 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

Returns:

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.