Supervisor Normal Operation Mode

Introduction

The Supervisor Normal Operation Mode is the usual mode an application wants to run the network in, within a production system. The target is to run the network in an "Available.Regular" state and to have all network nodes initialized and all activated routes built.

Therefore the Supervisor Normal Operation Mode must perform the following tasks:

• Force the network into "Available.Regular" state, and re-establish this state if necessary.
• Initialize all network nodes:
  • Run the NodeDiscovery process and welcome all nodes which are registered within the Network Descriptor. Thereby, a network node will adopt the 16-bit node address which is present in its signature.
  • Run the initialization script which is registered for the particular node.
  • Activate the Routing Management for the particular node. If both nodes of a route are initialized and the route is set to active, it will be built by the Routing Management.
• Observe and handle the network availability and resets of remote nodes.

The Network Descriptor

The Network Descriptor is a listing of all known nodes and routes that are expected in the specified network. A node or route which is not listed withing the Network Descriptor is not applicable. I.e., if an application requires to handle multiple network setups in a production system, it will need either to define multiple Network Descriptors (on for each target system) or a single Network Descriptor comprising a superset of all nodes and routes.

The Network Descriptor contains the following information:

• A list of all nodes:
  • A node is identified by the node_address field which is specified in the related signature. (The other fields of the signature are currently not used by the Network Supervisor to identify the node.)
  • The specified node_address must be unique within the list of all nodes.
  • It is possible to specify an initialization script which is automatically executed by the Network Supervisor when the node is discovered and initialized. The commands are restricted to GPIO and I2C functions.
• A list of all routes:
  • A route consists of one source and one sink endpoint.
  • Each endpoint refers to one node structure (which must be part of the nodes list) and to a NULL-terminated job list.
  • The job list is a specification of resource objects that must be created to build the endpoint.
  • It is possible to specify the route as active. This means as soon as the source and sink nodes are initialized the route will be built automatically. If the application uses a dynamic approach for the Routing Management it is possible to call Ucs_Rm_SetRouteActive() to change the active attribute during runtime.

The following example code specified two nodes and one route. The route is specified as active so that the route is build as soon as both nodes are discovered and initialized. The local INIC (root node) is expected to be configured with node_address 0x200.

/*------------------------------------------------------------------------------------------------*/
/* Nodes                                                                                          */
/*------------------------------------------------------------------------------------------------*/
#define APP_NODES_NUM 2U
static Ucs_Signature_t signature200  = {0x200U /*node_address*/};
static Ucs_Signature_t signature205 = {0x205U /*node_address*/};
static Ucs_Rm_Node_t app_nodes[APP_NODES_NUM] = {{&signature200, NULL, 0U}, /* root node */
                                                 {&signature205, NULL, 0U}};/* remote node */

/*------------------------------------------------------------------------------------------------*/
/* Routes                                                                                         */
/*------------------------------------------------------------------------------------------------*/
/* Specification of XRM JOB OUT */
static Ucs_Xrm_NetworkSocket_t        Xrm_Nw_Sckt_Out = {UCS_XRM_RC_TYPE_NW_SOCKET,
                                                         0x0D00U,
                                                         UCS_SOCKET_DIR_OUTPUT,
                                                         UCS_NW_SCKT_SYNC_DATA,
                                                         2U};
static Ucs_Xrm_DefaultCreatedPort_t    Xrm_Usb_Port_1 = {UCS_XRM_RC_TYPE_DC_PORT, 
                                                         UCS_XRM_PORT_TYPE_USB,
                                                         0U};
static Ucs_Xrm_UsbSocket_t          Xrm_Usb_Socket_In = {UCS_XRM_RC_TYPE_USB_SOCKET,
                                                         &Xrm_Usb_Port_1,
                                                         UCS_SOCKET_DIR_INPUT,
                                                         UCS_USB_SCKT_SYNC_DATA,
                                                         0x01U/*endpoint*/,
                                                         0x0007U /*frames*/};
static Ucs_Xrm_SyncCon_t            Xrm_Sync_Conn_Src = {UCS_XRM_RC_TYPE_SYNC_CON,
                                                         &Xrm_Usb_Socket_In,
                                                         &Xrm_Nw_Sckt_Out,
                                                         UCS_SYNC_MUTE_MODE_NO_MUTING,
                                                         0U};

/* Specification of XRM JOB IN */
static Ucs_Xrm_NetworkSocket_t         Xrm_Nw_Sckt_In = {UCS_XRM_RC_TYPE_NW_SOCKET,
                                                         0x0D00U,
                                                         UCS_SOCKET_DIR_INPUT,
                                                         UCS_NW_SCKT_SYNC_DATA,
                                                         2U};
static Ucs_Xrm_DefaultCreatedPort_t    Xrm_Usb_Port_2 = {UCS_XRM_RC_TYPE_DC_PORT,
                                                         UCS_XRM_PORT_TYPE_USB, 0U};
static Ucs_Xrm_UsbSocket_t         Xrm_Usb_Socket_Out = {UCS_XRM_RC_TYPE_USB_SOCKET,
                                                         &Xrm_Usb_Port_2,
                                                         UCS_SOCKET_DIR_OUTPUT,
                                                         UCS_USB_SCKT_SYNC_DATA,
                                                         0x81U/*endpoint*/,
                                                         0x0007U/*frames*/};
static Ucs_Xrm_SyncCon_t           Xrm_Sync_Conn_Sink = {UCS_XRM_RC_TYPE_SYNC_CON,
                                                         &Xrm_Nw_Sckt_In,
                                                         &Xrm_Usb_Socket_Out,
                                                         UCS_SYNC_MUTE_MODE_NO_MUTING,
                                                         0U};

/* Specification of the XRM jobs lists */
static Ucs_Xrm_ResObject_t * xrm_job_out[] = {&Xrm_Nw_Sckt_Out, &Xrm_Usb_Port_1, &Xrm_Usb_Socket_In,
                                              &Xrm_Sync_Conn_Src, NULL};
static Ucs_Xrm_ResObject_t * xrm_job_in[]  = {&Xrm_Nw_Sckt_In,  &Xrm_Usb_Port_2, &Xrm_Usb_Socket_Out,
                                              &Xrm_Sync_Conn_Sink, NULL};

/* Source and Sink Endpoints */
static Ucs_Rm_EndPoint_t endpoint_src      = {UCS_RM_EP_SOURCE, &xrm_job_out[0], &app_nodes[0]};
static Ucs_Rm_EndPoint_t endpoint_sink     = {UCS_RM_EP_SINK,   &xrm_job_in[0],  &app_nodes[1]};

/* Routes Specification */
#define APP_ROUTES_NUM          1U
static Ucs_Rm_Route_t app_routes[APP_ROUTES_NUM] = { {  &endpoint_src,
                                                        &endpoint_sink, 
                                                        true /*is_active*/,
                                                        66U  /* route_id */}
                                                   };

Note

It is important that each node in the "list of nodes" has a valid pointer to a node signature. Within the node signature the node_address attribute must be set to the value as set in the "identification string" of the respective node (INIC). Each node must be configured with a unique node_address. Other values inside the identification string are not evaluated by the Network Supervisor.

Initialization

Example

The Supervisor Normal Operation Mode provides several attributes to specify the target network state. Besides the list of nodes and routes the application can specify the target packet bandwidth and also proxy channel bandwidth. The proxy channel bandwidth is required if you specify static connections which are automatically created by the INIC if the network reaches the "Available.Regular" state.

The following example shows a typical initialization as it is required to run the Supervisor Normal Operation Mode with the Network Descriptor shown above.

void App_Initialize(void)
{
    Ucs_InitData_t init_data;
    Ucs_SetDefaultConfig(&init_data);

    /* Network Events */
    init_data.network.status.notification_mask = (UCS_NW_M_AVAIL) | (UCS_NW_M_NODE_POS);
    init_data.network.status.cb_fptr = &App_OnNetworkStatus;

    /* Routing Events */
    init_data.rm.report_fptr = &App_OnRoutingResult;

    /* GPIO */
    init_data.gpio.trigger_event_status_fptr = &App_OnGpioTriggerEventCb;

    /* Network Supervisor */
    init_data.supv.mode = UCS_SUPV_MODE_NORMAL;
    init_data.supv.report_mode_fptr = &App_OnSupvReportMode;

    /* Normal Operation Mode */
    init_data.supv.report_fptr = &App_OnSupvReport;
    init_data.supv.packet_bw = 52U;
    init_data.supv.proxy_channel_bw = 0U;
    init_data.supv.nodes_list_ptr = &app_nodes[0];
    init_data.supv.nodes_list_size = APP_NODES_NUM;
    init_data.supv.routes_list_ptr = &app_routes[0];
    init_data.supv.routes_list_size = APP_ROUTES_NUM;

    /* ... further initialization ... */

    Ucs_Init(&init_data, &App_OnInitResult);
}

See also Getting Started, section Initialization.

See also Getting Started, section Network Supervisor.

General Events

An application typically registers for the following general events:

• The network status callback function is typically used to notify when the network availability or the number of nodes changes. The application can use a mask to specify the events the callback shall be invoked.
• The should register to routing events. Routing events are fired if a route was successfully built or destroyed.
• If the peripheral bus interfaces are used on the local or remote INICs the respective GPIO trigger event callback is invoked after the node initialization or on GPIO event.

See also Getting Started, section Network.

See also Getting Started, section Routing Management.

See also Getting Started, section Peripheral Bus Interface.

Status Reports

If the application logic requires information about the availability of nodes, it is possible to register an optional callback function supv.report_fptr. This function is only triggered during Supervisor Normal Operation Mode. The following code shows simple implementation of this function.

static void App_OnSupvReport(Ucs_Supv_Report_t code, Ucs_Signature_t *signature_ptr, 
                             Ucs_Rm_Node_t *node_ptr, void *user_ptr)
{
    const char * code_str = "UNKNOWN";

    switch (code)
    {
        case UCS_SUPV_REP_NOT_AVAILABLE:
            code_str = "NOT_AVAILABLE";
            break;
        case UCS_SUPV_REP_IGNORED_UNKNOWN:
            code_str = "IGNORED_UNKNOWN";
            break;
        case UCS_SUPV_REP_IGNORED_DUPLICATE:
            code_str = "IGNORED_DUPLICATE";
            break;
        case UCS_SUPV_REP_WELCOMED:
            code_str = "WELCOMED";
            break;
        case UCS_SUPV_REP_SCRIPT_FAILURE:
            code_str = "SCRIPT_FAILURE";
            break;
        case UCS_SUPV_REP_IRRECOVERABLE:
            code_str = "IRRECOVERABLE";
            break;
        case UCS_SUPV_REP_SCRIPT_SUCCESS:
            code_str = "SCRIPT_SUCCESS";
            break;
        case UCS_SUPV_REP_AVAILABLE:
            code_str = "AVAILABLE";
            break;
        default:
            break;
    }
    
    if (signature_ptr != NULL)
    {
        printf( "App_OnSupvReport(): code=%s, node_addr=0x%04X, group_addr=0x%04X, node_ptr=0x%p\n", 
                code_str, 
                signature_ptr->node_address,
                signature_ptr->group_address,
                (void*)node_ptr);
    }
}