Ucs_Return_t Ucs_Rm_Start	(	Ucs_Inst_t *	self,
		Ucs_Rm_Route_t *	routes_list,
		uint16_t	list_size
	)

Initializes the routing process with the given routes list information and starts the process to handle the route(s).

When calling this function the routing management will be initialized and the process to handle the given routes list started. The result of each route is reported via the reference to the user callback function report_fptr in Ucs_InitData_t (if It has been set by user).

Parameters

self	The UNICENS instance pointer.
routes_list	List of routes to be handled.
list_size	Size of the given routes list.

Returns

Possible return values are shown in the table below.

Value	Description
UCS_RET_SUCCESS	No error
UCS_RET_ERR_PARAM	At least one parameter is NULL
UCS_RET_ERR_API_LOCKED	API is currently locked
UCS_RET_ERR_NOT_INITIALIZED	UNICENS is not initialized

Note

This function must be called once and can only be called once. Otherwise, the function returns the error code UCS_RET_ERR_API_LOCKED.

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 error, processing error, 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.

Attention

To suit your specific system needs and setup, change the default values of the following Resources Management macros:

• 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

Use the UCS_ADDR_LOCAL_DEV macro to address the local device when specifying connection routes to or from this device.
The following address ranges are supported:

• [0x10 ... 0x2FF]
• [0x500 ... 0xFEF]
• UCS_ADDR_LOCAL_DEV

Example

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

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

// XRM jobs lists
static Ucs_Xrm_ResObject_t * xrm_job_out[] = { &Xrm_Most_Sckt_Out, &Xrm_Usb_Port_1, &Xrm_Usb_Sckt_In,  &Xrm_Sync_Conn_1, NULL };
static Ucs_Xrm_ResObject_t * xrm_job_in [] = { &Xrm_Most_Sckt_In,  &Xrm_Usb_Port_2, &Xrm_Usb_Sckt_Out, &Xrm_Sync_Conn_2, NULL };

// Signatures specification
Ucs_Signature_t src_sig  = { 0x555U };
Ucs_Signature_t sink_sig = { 0x556U };

// Nodes objects
static Ucs_Rm_Node_t node_src  = { &src_sig  };
static Ucs_Rm_Node_t node_sink = { &sink_sig };

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

// 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;
   (void)Ucs_SetDefaultConfig(&ucs_init_data);
   ucs_init_data.rm.report_fptr = &App_OnRoutingResult;

   // 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
   }
   
   // Set corresponding Nodes to "available" if they are ready
   // (void)Ucs_Rm_SetNodeAvailable(ucs_inst_ptr, &node_src,  true);
   // (void)Ucs_Rm_SetNodeAvailable(ucs_inst_ptr, &node_sink, 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)
{
     // 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;
     }
}