AMiRo-OS

/'

µRtWare is a lightweight publish/subscribe middleware for real-time

applications. It was developed as part of the software habitat for the

Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well.

Copyright (C) 2018..2020  Thomas Schöpping et al.

This program is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

(at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program.  If not, see <http://www.gnu.org/licenses/>.

'/

/'### INTRO ##################################################################'/

@startuml

title **µRtWare**\nRemote Procedure Call System

!include ./functions.iuml

/'### ENTITIES ###############################################################'/

!startsub ENTITIES

$group("request") {

  /' Base request structure type. '/

  $structure("urt_baserequest_t") {

      'Pointer to the previous request in a queue.

    + {field} prev : urt_baserequest_t*

      'Pointer to the next request in a queue.

    + {field} next : urt_baserequest_t*

      'Lock for exclusive access.

    + {field} lock : urt_osMutex_t

      'Pointer to the owning service.

    + {field} owner : urt_service_t*

      'Time when the request was submitted.

    + {field} submissionTime : urt_osTime_t

      'Pointer to an optional payload of the service request.

    + {field} payload : void*

      'Source for service events.

    + {field} evtSource : urt_osEventSource_t

      'Listener to service events.

    + {field} evtListener : urt_osEventListener_t

    .. URT_CFG_RPC_PROFILING == true ..

      'Sum of all latencies.

    + {field} sumLatencies : uint64_t

      'Number of calls emitted.

    + {field} numCalls : uint64_t

      'Number of calls that were not processed successfully.

    + {field} numFails : uint64_t

  }

  /' NRT request type. '/

  $structure("urt_nrtrequest_t") {

    .. URT_CFG_RPC_PROFILING == true ..

      'Minimum latency ever detected.

    + {field} minLatency : urt_delay_t

      'Maximum latency ever detected.

    + {field} maxLatency : urt_delay_t

    __

      'Initializes a urt_nrtrequest_t object.

    + {method} urtNrtRequestInit (request : urt_nrtrequest_t*) : void

      'Acquire and lock an NRT request (blocking).

    + {method} urtNrtRequestAcquire (request : urt_nrtrequest_t*) : urt_status_t

      'Try to acquire and lock an NRT request (non blocking).

    + {method} urtNrtRequestTryAcquire (request : urt_nrtrequest_t*) : urt_status_t

      'Release an acquired/locked NRT request.

    + {method} urtNrtRequestRelease (request : urt_nrtrequest_t*) : urt_status_t

      'Submit an NRT request to the specified service.

    + {method} urtNrtRequestSubmit (request : urt_nrtrequest_t*, service : urt_service_t*) : urt_status_t

      'Retrieve an NRT request, thereby removing it from the service's request queue if required.

    + {method} urtNrtRequestRetrieve (request : urt_nrtrequest_t*) : urt_status_t

  }

  /' SRT request type. '/

  $structure("urt_srtrequest_t") {

    .. URT_CFG_RPC_PROFILING == true ..

      'Minimum latency ever detected.

    + {field} minLatency : urt_delay_t

      'Maximum latency ever detected.

    + {field} maxLatency : urt_delay_t

    __

      'Initializes a urt_srtrequest_t object.

    + {method} urtSrtRequestInit (request : urt_srtrequest_t*) : void

      'Acquire and lock an SRT request (blocking).

    + {method} urtSrtRequestAcquire (request : urt_srtrequest_t*) : urt_status_t

      'Try to acquire and lock an SRT request (non blocking).

    + {method} urtSrtRequestTryAcquire (request : urt_srtrequest_t*) : urt_status_t

      'Release an acquired/locked SRT request.

    + {method} urtSrtRequestRelease (request : urt_srtrequest_t*) : urt_status_t

      'Submit an SRT request to the specified service.

    + {method} urtSrtRequestSubmit (request : urt_srtrequest_t*, service : urt_service_t*) : urt_status_t

      'Retrieve an SRT request, thereby removing it from the service's request queue if required.

    + {method} urtSrtRequestRetrieve (request : urt_srtrequest_t*) : urt_status_t

      'Calculate the usefulness on an SRT RPC response.

    + {method} urtSrtCalculateUsefulness (request : urt_srtrequest_t*, usefulnesscb : urt_usefulness_f, cbparams : void*) : float

  }

  /' FRT request type. '/

  $structure("urt_frtrequest_t") {

    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true ..

      'Maximum temporal offset between sending and consuming the FRT request.

    + {field} deadlineOffset : urt_delay_t

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..

      'Maximum expected jitter.

    + {field} maxJitter : urt_delay_t

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true || URT_CFG_RPC_PROFILING == true ..

      'Minimum latency ever detected (to calculate jitter).

    + {field} minLatency : urt_delay_t

      'Maximum latency ever detected (to calculate jitter).

    + {field} maxLatency : urt_delay_t

    __

      'Initializes a urt_frtrequest_t object.

    + {method} urtFrtRequestInit (request : urt_frtrequest_t*) : void

      'Acquire and lock an FRT request (blocking).

    + {method} urtFrtRequestAcquire (request : urt_frtrequest_t*) : urt_status_t

      'Try to acquire and lock an FRT request (non blocking).

    + {method} urtFrtRequestTryAcquire (request : urt_frtrequest_t*) : urt_status_t

      'Release an acquired/locked FRT request.

    + {method} urtFrtRequestRelease (request : urt_frtrequest_t*) : urt_status_t

      'Submit an FRT request to the specified service.

    + {method} urtFrtRequestSubmit (request : urt_frtrequest_t*, service : urt_service_t*, deadline : urt_delay_t) : urt_status_t

      'Retrieve an FRT request, thereby removing it from the service's request queue if required.

    + {method} urtFrtRequestRetrieve (request : urt_frtrequest_t*) : urt_status_t

      'Calculate the validity on an FRT RPC response.

    + {method} urtDrtCalculateValidity (request : urt_frtrequest_t) : bool

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..

      'Get a pointer to the request's maximum jitter value.

    + {method} urtFrtRequestGetMaxJitter (request : urt_frtrequest_t*) : urt_delay_t* const

  }

  /' HRT request type. '/

  $structure("urt_hrtrequest_t") {

    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true ..

      'Maximum temporal offset between sending and consuming the HRT request.

    + {field} deadlineOffset : urt_delay_t

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..

      'Maximum expected jitter.

    + {field} maxJitter : urt_delay_t

    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true || URT_CFG_RPC_QOS_JITTERCHECKS == true ..

      'QoS timer to detect missed deadlines and/or jitter.

    + {field} qosTimer : urt_osTimer_t

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true || URT_CFG_RPC_PROFILING == true ..

      'Minimum latency ever detected (to calculate jitter).

    + {field} minLatency : urt_delay_t

      'Maximum latency ever detected (to calculate jitter).

    + {field} maxLatency : urt_delay_t

    __

      'Initializes a urt_hrtrequest_t object.

    + {method} urtHrtRequestInit (request : urt_hrtrequest_t*) : void

      'Acquire and lock an HRT request (blocking).

    + {method} urtHrtRequestAcquire (request : urt_hrtrequest_t*) : urt_status_t

      'Try to acquire and lock an HRT request (non blocking).

    + {method} urtHrtRequestTryAcquire (request : urt_hrtrequest_t*) : urt_status_t

      'Release an acquired/locked HRT request.

    + {method} urtHrtRequestRelease (request : urt_hrtrequest_t*) : urt_status_t

      'Submit an HRT request to the specified service.

    + {method} urtHrtRequestSubmit (request : urt_hrtrequest_t*, service : urt_service_t*, deadline : urt_delay_t) : urt_status_t

      'Retrieve an HRT request, thereby removing it from the service's request queue if required.

    + {method} urtHrtRequestRetrieve (request : urt_hrtrequest_t*) : urt_status_t

    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..

      'Get a pointer to the request's maximum jitter value.

    + {method} urtHrtRequestGetMaxJitter (request : urt_hrtrequest_t*) : urt_delay_t* const

  }

}

/' Service structure type. '/

$structure("urt_service_t") {

    'Pointer to the next service in a list.

  + {field} next : urt_service_t*

    'Identifier of the service.

  + {field} id : urt_serviceid_t

    'Mutex lock for exclusive access.

  + {field} lock : urt_osMutex_t

    'Pointer to the first element in a queue of pending requests.

  + {field} requestQueue_front : urt_baserequest_t*

    'Pointer to the last HRT request in a queue of pending requests.

  + {field} requestQueue_hrtBack : urt_hrtrequest_t*

    'Pointer to the last FRT/SRT request in a queue pf pending requests.

  + {field} requestQueue_fsrtBack : urt_baserequest_t*

    'Pointer to the last element in a queue of pending requests.

  + {field} requestQueue_back : urt_baserequest_t*

    'Event source to be fired by requests.

  + {field} evtSource : urt_osEventSource_t

    'Event listener to notify the service thread.

  + {field} evtListener : urt_osEventListener_t

  .. URT_CFG_RPC_PROFILING == true ..

    'Number of calls.

  + {field} numCalls : uint64_t

    'Number of lost ownerships.

  + {field} numOwnershipLost : uint64_t

  __

    'Initializes a urt_service_t object.

  + {method} urtServiceInit (service : urt_service_t*, id : urt_serviceid_t) : urt_status_t

    'Dispatch the next pending request.

  + {method} urtServiceDispatch (service : urt_service_t*, payload : void*, bytes : size_t) : urt_baserequest_t*

    'Acquire and lock the specified request (blocking).

  + {method} urtServiceAcquireRequest (service* urt_serviceid_t*, request : urt_baserequest_t*) : urt_status_t

    'Acquire and lock the specified request (non blocking).

  + {method} urtServiceTryAcquireRequest (service* urt_serviceid_t*, request : urt_baserequest_t*) : urt_status_t

    'Respond to a request.

  + {method} urtServiceRespond (request : urt_baserequest_t*) : urt_status_t

}

!endsub

/'### DEPENDENCIES & LAYOUT ##################################################'/

!startsub DEPENDENCIES

urt_baserequest_t "1" o- "0,1,2" urt_baserequest_t

urt_baserequest_t "1" o- "0,1" urt_service_t

urt_nrtrequest_t --|> urt_baserequest_t

urt_nrtrequest_t ..> urt_service_t

urt_srtrequest_t --|> urt_baserequest_t

urt_srtrequest_t ..> urt_service_t

urt_frtrequest_t --|> urt_baserequest_t

urt_frtrequest_t ..> urt_service_t

urt_hrtrequest_t --|> urt_baserequest_t

urt_hrtrequest_t ..> urt_service_t

urt_service_t "1" o- "0,1" urt_service_t

urt_service_t "1" o- "0,2,3" urt_baserequest_t

urt_service_t "1" o- "0,1" urt_hrtrequest_t

!endsub

/'### OUTRO ##################################################################'/

@enduml