Routing Management

Introduction

The routing management is an aspect of the INIC Resources Management that implements the connectivity between sources and sinks endpoints respectively sockets from a device perspective (see picture below).

A (virtual) route is a logical unidirectional connection between two endpoints. An endpoint acts as a MOST connection in INIC plus the internal linked resources.
The routing management consists of 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.
• 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.most_port_status_fptr: Optional callback function that reports streaming-related information for the MOST 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.

The example below 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.most_port_status_fptr  = &App_MostPortStatusCb;
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 cannot be processed anymore due to Unicens Termination */
            break;
        default:
            /* Route has been suspended */
            break;
    }
}

/* Handle MOST Port Status event here */
void App_MostPortStatusCb(uint16_t most_port_handle,
                            Ucs_Most_PortAvail_t availability,
                            Ucs_Most_PortAvailInfo_t avail_info,
                            uint16_t free_streaming_bw)
{
    /* Do what needs to be.. */
}

/* Handle the Mute Pin check here */
void App_CheckUnmuteStatusCb (uint16_t node_address)
{
    /* 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

After initialization the application specifies the routes, endpoints, nodes as well as the XRM jobs and calls the Ucs_Rm_Start() function to initialize and start the routing process. This function must be called once and can only be called once. At this point, it is important to mention that there are some preconditions for the routes to be handled properly:

• UNICENS is initialized
• XRM macros have been set correctly (See above)
• The network is available
• The nodes, where the corresponding routes shall be built on, are available. That is, the user application has to call the function Ucs_Rm_SetNodeAvailable() whenever the node is available or the node is unavailable. In case the node is unavailable all created resources related to the node will be internally released and the user will receive a notification via the given callback functions report_fptr and debug_resource_status_fptr in Ucs_Rm_InitData_t.

In short the user application can anytime call the function Ucs_Rm_Start() with the specified list of routes but these routes will have been processing only when the above conditions are met.

It is important to note that, The build up of routes can take some times 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.). By the way, 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, ...);

Example

The following example outlines the construction of a route between a local (Master) and a remote device incl. the settings of the above preconditions. In this example the UCS_ADDR_LOCAL_DEV 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.

/***************************************************************************************************
                 DESCRIPTION OF THE SPECIFIED ROUTE_66 (Refer to the above picture)
                                                                                                    
  
   Source Endpoint [Synchronous Data Connection "Application -> Streaming Port -> MOST"]:
        - 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
        - MOST Socket:
            - Direction: Output
            - Data type: Sync Data
            - MOST Port Handle: 0x0D00
            - Bandwidth: 2 bytes
  
   Sink Endpoint [Synchronous Data Connection "MOST -> 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
        - MOST Socket:
            - Direction: Input
            - Data type: Sync Data
            - MOST Port Handle: 0x0D00
            - Bandwidth: 2 bytes
  
 *--------------------------------------------------------------------------------------------------
 */

/* 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;    

/* Specification of XRM JOB OUT */
 static Ucs_Xrm_MostSocket_t Xrm_Most_Sckt_Out = { UCS_XRM_RC_TYPE_MOST_SOCKET, 0x0D00U, UCS_SOCKET_DIR_OUTPUT, UCS_MOST_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_Most_Sckt_Out, UCS_SYNC_MUTE_MODE_NO_MUTING, 0U };

 /* Specification of XRM JOB IN */
 static Ucs_Xrm_MostSocket_t Xrm_Most_Sckt_In   = { UCS_XRM_RC_TYPE_MOST_SOCKET, 0x0D00U, UCS_SOCKET_DIR_INPUT, UCS_MOST_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_Most_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_Most_Sckt_Out, &Xrm_Str_Port_A, &Xrm_Str_Socket_In,  &Xrm_Sync_Conn_Src, NULL };
static Ucs_Xrm_ResObject_t * xrm_job_in [] = { &Xrm_Most_Sckt_In,  &Xrm_Mlb_Port, &Xrm_Mlb_Socket_Out, &Xrm_Sync_Conn_Sink, NULL };

/* Specification of signatures objects */
Ucs_Signature_t src_sig  = { UCS_ADDR_LOCAL_DEV };
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} };

/* 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 (!rtm_is_started)
            {
                rtm_is_started = true;

                /* Network start-up */
                Ucs_Network_Startup(ucs_inst_ptr, 52U, 0xFFFFU, NULL);

                /* Starts routes processing */
                Ucs_Return_t ret_value = Ucs_Rm_Start(ucs_inst_ptr, &route_66[0], 1U);
                if (ret_value != UCS_RET_SUCCESS)
                {
                    /* Do whatever is necessary here */
                }
            }

            if (set_ampl_to_available)
            {
                Ucs_Rm_SetNodeAvailable(ucs_inst_ptr, &ampl_node, true);
            }

            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_SetNodeAvailable() : This function sets the availability attribute (available or not available) of the given node and triggers the routing process to handle attached route(s).
• Ucs_Rm_GetNodeAvailable() : This function retrieves the "available" flag information of a given node.
• Ucs_Rm_GetAttachedRoutes() : This function retrieves the references of the routes attached to the given endpoint.
• Ucs_Rm_GetConnectionLabel(): This function retrieves the ConnectionLabel of the given route.