Routing Management

Introduction

The Routing Management is an aspect of the INIC Resources Management. Its responsibility is the connectivity between source and sink endpoints (see picture below).

A (virtual) route is a logical unidirectional connection between two endpoints. An endpoint acts as an INIC internal connection and consists of internal linked resources.
The routing management offers the following features:

• Create a route
• Destroy a route
• Monitor created routes and XRM resources
• Report each route state to the user application callback functions.

The UNICENS library provides therefore a set of functions to fulfill the above features. These will be depicted in the next sections.

Configuration

Since the routing management is based on XRM (refer to MNS V3.2.x), the user has to change the default values of the following macros to suit his specific system needs.

• UCS_NUM_REMOTE_DEVICES in ucs_cfg.h
• UCS_XRM_NUM_JOBS in ucs_xrm_cfg.h
• UCS_XRM_NUM_RESOURCES in ucs_xrm_cfg.h

/* File: ucs_cfg.h */
#define UCS_NUM_REMOTE_DEVICES  10U

/* File: ucs_xrm_cfg.h */
#define UCS_XRM_NUM_JOBS        40U
#define UCS_XRM_NUM_RESOURCES  200U

Initialization

The application shall provide following report callback functions in the UNICENS Init-Structure in order to receive any routing events. These are:

• rm.report_fptr: Optional callback function that reports status information for all routes. The passed result callback function does not only report the result of the build operation but also monitors the status of the created routes during their whole lifetime. That is, the callback function also reports the various states of a route (Refer to Ucs_Rm_RouteInfos_t for more infos). Furthermore the result of Ucs_Rm_SetRouteActive() function call is reported by this result callback function as well as the status of the ATD feature, if it is enabled for the route.

  Handling the states:

  • Built: The route has been built. From this state a route can be deactivated respectively destroyed by the application or "auto-destroyed" if a system error occurs.
  • Destroyed: The route has been destroyed successfully. The job has been instructed by the user application.
  • Suspended: The route enters this state if critical configuration errors or temporary critical network errors occur or the maximum number of auto retries after uncritical errors has reached. The route will remain in this state until user intervention. The route can be reactivated by setting it to "inactive" first and than build the route again by setting it to "active".
  • ATD Update available: An ATD update is available for the corresponding route. This is caused due to a route build event or the number of the nodes in the network changed.
  • ATD Error: The ATD value could not be calculated for the corresponding route.

• rm.debug_resource_status_fptr: Optional callback function that acts as a debug interface for XRM resources. User application can monitor the specified XRM resources via this interface.
• rm.xrm.nw_port_status_fptr: Optional callback function that reports streaming-related information for the Network Port
• rm.xrm.check_unmute_fptr: Optional callback function that signals the EHC to check the mute pin state of devices before attempting an unmute.

Example

The code example illustrates how to initialize these callback functions:

Ucs_InitData_t ucs_init_data;
(void)Ucs_SetDefaultConfig(&ucs_init_data);

/* Routing Management init section. */
ucs_init_data.rm.report_fptr                = &App_OnRoutingResult;
ucs_init_data.rm.debug_resource_status_fptr = &App_OnDebuggingXrmResources;
ucs_init_data.rm.xrm.nw_port_status_fptr    = &App_Network_PortStatusCb;
ucs_init_data.rm.xrm.check_unmute_fptr      = &App_CheckUnmuteStatusCb;

/* The report callback function for all routes */
static void App_OnRoutingResult(uint16_t route_id, Ucs_Rm_RouteInfos_t route_infos, void *user_ptr)
{
    /* Do whatever is necessary here */

    switch (route_infos)
    {
        case UCS_RM_ROUTE_INFOS_BUILT:
            /* Route has been built */
            break;
        case UCS_RM_ROUTE_INFOS_DESTROYED:
            /* Route has been destroyed */
            break;
        case UCS_RM_ROUTE_INFOS_PROCESS_STOP:
            /* Route can not be processed anymore due to UNICENS Termination */
            break;
        case UCS_RM_ROUTE_INFOS_ATD_UPDATE:
            /* ATD update available */
            /* Do whatever is necessary here, e.g. Ucs_Rm_GetAtdValue() */
            break;
        case UCS_RM_ROUTE_INFOS_ATD_ERROR:
            /* ATD error occurred */
            break;
        default:
            /* Route has been suspended */
            break;
    }
}

/* Handle network Port Status event here */
void App_Network_PortStatusCb(uint16_t nw_port_handle,
                          Ucs_Network_PortAvail_t availability,
                          Ucs_Network_PortAvailInfo_t avail_info,
                          uint16_t free_streaming_bw,
                          void* user_ptr)
{
    /* Do what needs to be.. */
}

/* Handle the Mute Pin check here */
void App_CheckUnmuteStatusCb(uint16_t node_address, void *user_ptr)
{
    /* Check the state of the mute pin here before unmuting */
}

/* Debug interface for the XRM resources */
void App_OnDebuggingXrmResources(Ucs_Xrm_ResourceType_t resource_type,
                                 Ucs_Xrm_ResObject_t *resource_ptr,
                                 Ucs_Xrm_ResourceInfos_t resource_infos,
                                 Ucs_Rm_EndPoint_t *endpoint_inst_ptr,
                                 void *user_ptr)
{
    switch (resource_infos)
    {
        case UCS_XRM_INFOS_BUILT:
            /* Resource has been built */
            break;
        case UCS_XRM_INFOS_DESTROYED:
            /* Resource has been destroyed */
            break;
        case UCS_XRM_INFOS_ERR_BUILT:
            /* Resource cannot be built */
            break;
        default:
            /* Resource cannot be destroyed */
            break;
    }
}

Operation

The basic handling of routing management is done by the supervisor. Have a look at the supervisors Normal Operation Mode Supervisor Normal Operation Mode. Nevertheless, the application can activate or deactivate specific routes using the Ucs_Rm_SetRouteActive() function.

It is important to note that, the build up of routes can take some time, in case the routing process may need to perform retries when uncritical errors occur (e.g.: transmission errors, processing errors, etc) or when certain conditions are not met yet (e.g. network not available, node not available, etc.). As an aside, the maximum number of retries is 0xFF and the minimum time between the retries is 50ms.

Also note that enabling the error and event trace output in ucs_cfg.h file (see below) will help user get detailed information on routes during processing.

/* File: ucs_cfg.h */
/*------------------------------------------------------------------------------------------------*/
/* Tracing & Debugging                                                                            */
/*------------------------------------------------------------------------------------------------*/
# define UCS_TR_ERROR     App_TraceError
# define UCS_TR_INFO      App_TraceInfo

extern void App_TraceError(void *ucs_user_ptr, const char module_str[], const char entry_str[],
                           uint16_t vargs_cnt, ...);
extern void App_TraceInfo(void *ucs_user_ptr, const char module_str[], const char entry_str[],
                           uint16_t vargs_cnt, ...);

Implementation Guide

The following example outlines the construction of a route between a local (Master) and a remote device inclusive the settings of the above preconditions. In this example the UCS_ADDR_LOCAL_NODE macro is used to address the local device and should only be used for the local device.
This example is inserted as a guide and may not contain all of the necessary details and information.

Describing the route structure:

In this section the route structure is defined for the route shown in the picture. Therefore XRM jobs have to be set for the needed resources in the sink and source endpoint.

/*
  Source Endpoint [Synchronous Data Connection "Application -> Streaming Port -> Network"]:
       - Configuration Port A:
           - Operation Mode:   Generic
           - Port Option:      InOut
           - Clock Mode:       Output
           - Clock Data Delay: NonDelayed
       - Configuration Port B:
           - Operation Mode:   Generic
           - Port Option:      InOut
           - Clock Mode:       Output
           - Clock Data Delay: NonDelayed
       - Streaming Port A:
           - Clock Config:     64 Fs
           - Data Alignment:   Left16Bit
       - Streaming Socket:
           - Direction:        Input
           - Data Type:        Sync
           - Bandwidth:        2
           - Streaming Pin ID: SRXA0
       - Network Socket:
           - Direction:        Output
           - Data type:        Sync Data
           - Network Port Handle: 0x0D00
           - Bandwidth:        2 bytes
 
  Sink Endpoint [Synchronous Data Connection "Network -> MediaLB -> Application (INIC on I/O-Board)"]:
       - No Muting
       - MediaLB Port:
           - Clock Config:     512Fs
       - MediaLB Socket:
           - Direction:        Output
           - Data type:        Sync Data
           - Bandwidth:        2 bytes
           - Channel address:  0x000A
       - Network Socket:
           - Direction:        Input
           - Data type:        Sync Data
           - Network Port Handle: 0x0D00
           - Bandwidth:        2 bytes
*/

/* Specification of XRM jobs of the Source Endpoint */
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_StrmPort_t   Xrm_Str_Port_A     = { UCS_XRM_RC_TYPE_STRM_PORT,
                                                   0x00U,
                                                   UCS_STREAM_PORT_CLK_CFG_64FS,
                                                   UCS_STREAM_PORT_ALGN_LEFT16BIT };
static Ucs_Xrm_StrmSocket_t Xrm_Str_Socket_In  = { UCS_XRM_RC_TYPE_STRM_SOCKET,
                                                   &Xrm_Str_Port_A,
                                                   UCS_SOCKET_DIR_INPUT,
                                                   UCS_STREAM_PORT_SCKT_SYNC_DATA,
                                                   2U,
                                                   UCS_STREAM_PORT_PIN_ID_SRXA0 };
static Ucs_Xrm_SyncCon_t    Xrm_Sync_Conn_Src  = { UCS_XRM_RC_TYPE_SYNC_CON,
                                                   &Xrm_Str_Socket_In,
                                                   &Xrm_NW_Sckt_Out,
                                                   UCS_SYNC_MUTE_MODE_NO_MUTING,
                                                   0U };

/* Specification of XRM jobs of the Sink Endpoint*/
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_MlbPort_t    Xrm_Mlb_Port       = { UCS_XRM_RC_TYPE_MLB_PORT,
                                                   0x00U,
                                                   UCS_MLB_CLK_CFG_512_FS };
static Ucs_Xrm_MlbSocket_t  Xrm_Mlb_Socket_Out = { UCS_XRM_RC_TYPE_MLB_SOCKET,
                                                   &Xrm_Mlb_Port,
                                                   UCS_SOCKET_DIR_OUTPUT,
                                                   UCS_MLB_SCKT_SYNC_DATA,
                                                   2U,
                                                   0x000AU };
static Ucs_Xrm_SyncCon_t    Xrm_Sync_Conn_Sink = { UCS_XRM_RC_TYPE_SYNC_CON,
                                                   &Xrm_Nw_Sckt_In,
                                                   &Xrm_Mlb_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_Str_Port_A,
                                               &Xrm_Str_Socket_In,
                                               &Xrm_Sync_Conn_Src,
                                               NULL };
static Ucs_Xrm_ResObject_t * xrm_job_in [] = { &Xrm_NW_Sckt_In,
                                               &Xrm_Mlb_Port,
                                               &Xrm_Mlb_Socket_Out,
                                               &Xrm_Sync_Conn_Sink,
                                               NULL };

/* Specification of signatures objects */
static Ucs_Signature_t src_sig  = { UCS_ADDR_LOCAL_NODE };
static Ucs_Signature_t sink_sig = { 0x555U };

/* Specification of Nodes objects */
static Ucs_Rm_Node_t hmi_node  = { &src_sig };
static Ucs_Rm_Node_t ampl_node = { &sink_sig };

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

/* Routes Specification */
static Ucs_Rm_Route_t route_66[] = { {&endpoint_src, &endpoint_sink, is_active, 66U, 0x00U} };

Implementation to build the defined route:

The above defined route can be build by implementing and extending the following code example.

/* Forward declaration of results callback function */
static void App_OnRoutingResult(uint16_t route_id, Ucs_Rm_RouteInfos_t route_infos, void *user_ptr);
static void App_OnInitResult(Ucs_InitResult_t result, void *user_ptr);

/* Set app flags */
static bool app_is_running        = true;
static bool ucs_is_running        = false;
static bool ampl_is_discovered    = false;
static bool set_ampl_to_available = false;
static bool rtm_is_started        = false;

/* Set route Activity Flag */
static uint8_t is_active = 0x01U;

/* Main function */
void main ()
{
    Ucs_InitData_t ucs_init_data;
    /* create instance and prepare init structure */
    ucs_inst_ptr = Ucs_CreateInstance();
    (void) Ucs_SetDefaultConfig(&ucs_init_data);

    /* Routing Management init section. */
    ucs_init_data.rm.report_fptr = &App_OnRoutingResult;

    /* Library initialization */
    (void) Ucs_Init(inst_ptr, &init_data, &App_OnInitResult);

    while (app_is_running)
    {
        if (ucs_is_running)
        {
            if (ampl_is_discovered)
            {
                (void) Ucs_Xrm_Stream_SetPortConfig(ampl_node.signature_ptr->node_address,
                                                    0x00U,
                                                    UCS_STREAM_PORT_OP_MODE_GENERIC,
                                                    UCS_STREAM_PORT_OPT_IN_OUT,
                                                    UCS_STREAM_PORT_CLK_MODE_OUTPUT,
                                                    UCS_STREAM_PORT_CLK_DLY_NONE,
                                                    &App_XrmStreamPortCfgResCb);
            }
        }
    }
}

/* Notifies initialization result */
static void App_OnInitResult(Ucs_InitResult_t result, void *user_ptr)
{
   if (result == UCS_INIT_RES_SUCCESS)
   {
       ucs_is_running = true;
   }
}

/* The report callback function for all routes */
static void App_OnRoutingResult(Ucs_Rm_Route_t* route_ptr, Ucs_Rm_RouteInfos_t route_infos, void *user_ptr)
{
    switch (route_infos)
    {
        case UCS_RM_ROUTE_INFOS_BUILT:
            /* Route has been built */
            break;
        case UCS_RM_ROUTE_INFOS_DESTROYED:
            /* Route has been destroyed */
            break;
        case UCS_RM_ROUTE_INFOS_PROCESS_STOP:
            /* Route cannot be processed anymore due to UNICENS Termination */
            break;
        default:
            /* Route has been suspended */
            break;
    }
}

/* The result callback function for Streaming ports */
static void App_XrmStreamPortCfgResCb(uint16_t node_address,
                                     uint8_t index,
                                     Ucs_Stream_PortOpMode_t op_mode,
                                     Ucs_Stream_PortOption_t port_option,
                                     Ucs_Stream_PortClockMode_t clock_mode,
                                     Ucs_Stream_PortClockDataDelay_t clock_data_delay,
                                     Ucs_StdResult_t result,
                                     void *user_ptr)
{
    if (result.code == UCS_RES_SUCCESS)
    {
        set_ampl_to_available = true;
    }
}

Additional Routing API

The Routing provides additional API functions to handle some runtime tasks. These functions are:

• Ucs_Rm_SetRouteActive() : This functions sets a specific route to "active" or "inactive" at runtime.
• Ucs_Rm_GetNodeAvailable() : This function retrieves the "available" flag information of a given node.
• Ucs_Rm_GetConnectionLabel(): This function retrieves the ConnectionLabel of the given route.

Examples for Routing API

• Audio Transportation Delay
• Static Connections
• Routing Management and XRM Examples