INtime SDK Help
RT service calls (deprecated)

From INtime 6.0 the INtime Service and Port objects have been deprecated.

New projects should not be started using these features, and existing projects will not work with XM mode

Overview

This describes how to design and use an INtime service to perform a hardware driver capability, or to provide intermediate services between driver and application. The INtime Service is described in detail and examples given of certain key issues.

Hardware "driver" development for INtime

INtime software includes the features required to write an application which can control an I/O-mapped hardware device which generates interrupts. With INtime software, you can:

Advantages of using the service model to implement a hardware driver include:

Intermediate services

A hardware interface may be required to support multiple services to different applications. For example, a serial controller designed to transmit and receive streams of bytes could be enhanced by adding a service which organizes the bytes into packets, and switch the packets depending on the packet contents. This can be accomplished by writing an intermediate service to do the packet formatting and switching, and which uses a hardware service to transmit and receive the bytes.

Messaging Interface Features

The INtime service model is based on the INtime port object, which provides a messaging interface to a service. Messages may be sent to and received from a port. A given service is defined by:

Two services supporting the same message set are interchangeable. This makes for easy porting of applications between different hardware interfaces by careful design of the service interface.

A process which uses a service (a user process) may send or receive messages from more than one port, and more than one user process may use the same port.

A user process may fall into one of these categories:

INtime services

Functionally, the purpose of a service is to process messages from a user and events from an interface. A service is defined by the set of messages and the actions provoked by those messages. The user sending and receiving the messages via the port does not have to know the details of the service internals or of the interface. Two services supporting the same message set are interchangeable. This makes for easy porting of applications between different interfaces by careful design of the service message interface.

Service types

Services can classified in one of two broad categories.

A service may be further classified by the type of interface it serves. Hardware services typically include interrupt services, or alarm services while intermediate services are always port services.

Installation and configuration

INtime Services are dynamically loaded during run-time by loading the service process. When a service is loaded it must make a call to InstallRtServiceDescriptor to install each of its service descriptors before the service is made available to other applications.

Services may be configured by passing static parameters in the service descriptor, and by dynamically changing certain attributes using the primitive SetRtServiceAttributes. These and other attributes may be monitored using the primitive GetRtServiceAttributes. The implementation of these interfaces is optional.

A service may be removed by making a call to UninstallRtServiceDescriptor.

Service layers

Once a hardware service is installed, other intermediate services may be loaded to provide higher-level functionality. For example, services to provide different functionality may be loaded "on top" of a hardware service. During the initialization of the intermediate service it creates a port for access to the hardware service. Thus an intermediate service is itself a user process for another service. Intermediate services may also create ports into other intermediate services, providing a multi-layered architecture.

Service architecture

This section describes how Services are implemented and what decisions have to be made to achieve that implementation. It describes the architecture of a service and gives examples of different types of service.

Service structure

This picture illustrates the architecture of a service and its interaction with the INtime kernel:

Points to notice:

Service components

A service consists of four major components.

  1. Service descriptor: Contains information used by the INtime kernel when processing requests for a given service. This information includes such items as the service name, the resource parameters for the service, and the entry points for the service subroutines called by the kernel to handle service-specific functions.
  2. Interface: The entity which generates events which the service is designed to process. This interface can be a hardware interface which generates interrupts, or another system object such as an alarm event or mailbox. It can also be another port belonging to another service. The type of event generated is dependent on what the interface is. The events are handled by a service task which is created when the service is installed and initialized.
  3. Service thread: Scheduled by an event from the interface and must perform operations to service the event.
  4. Service handlers: Subroutines invoked by the kernel to perform service-dependent functions of the system calls. For example, calling SendRtMessage causes the kernel to invoke a subroutine called SendMessage supplied by the service in order to handle the transmission of the message to the interface. Some of these handlers must be supplied by the service; others are optional.
    The control and transaction buffer pools are the static resources used for allocating internal data structures. The size of these pools is determined from parameters in the service descriptor at installation time.

Internal control structures

Several internal control structures are defined and managed by the RT kernel to support message and transaction handling within a service. These structures contain details of each message and each transaction. When a service is initialized, a pool of each type of structure is created according to parameters given in the service descriptor.

INtime service control structures include:

CONTROLBUFFER
RECEIVEINFO
TRANSACTION

Service Library (RTSERV.LIB)

A library is provided for the service developer to allow access to system services specific to service requirements. It includes functions to manage the transaction and message buffer pools, to deliver messages to ports, queue management and port ID lookup services. A corresponding C header file (RTSERV.H) is also available in the standard include directories.

This library must be linked with each service application.

Implementing a service

Follow these steps to implement a service:

The items delivered by the implementer will be (as a minimum) a service application, and a header file for service users.

Transmit operations

The primitives SendRtMessage, SendRtMessageRSVP and SendRtReply all cause the kernel to invoke the compulsory handler SendMessage. This handler starts the transmit operation (however it is implemented in the service) and manages the send side of the service data path.

The routine is presented with a pointer to a transaction and a pointer to a control buffer, each of which has been initialized with the relevant system information. The implementer has the following responsibilities:

Receive operations

Receive operations are a little more complicated. In general, the service thread processes one or more events from the interface to generate a message, which it then delivers to a port. When a user calls ReceiveRtMessage or ReceiveRtReply the kernel formats all the information in the message buffer into the ReceiveInfo structure supplied by the caller. The service implementer may optionally specify a handler to handle unusual formatting requirements.


Fragmentation

Fragmentation describes the process where a given message is split up for transmission and must be put together again by the receiving entity. The fragmentation scheme for any given service is a function of the design of that service, and in general, not much support can be given to the implementer. However, to make a given fragmentation scheme easier to implement, certain fields are provided in the transaction structure and one interface is provided to help.

Service-specific System Calls

To . . . Use this system call . . .
Indicate a complete transactionless message is ready to deliver to a port. DeliverMessage
Terminate a transmit operation, usually from the service thread. DeliverStatus
Indicate a response message is ready to deliver to a port. DeliverTransaction
Dequeue the transaction at the head of the service input queue and returns a pointer to it. DequeueInputTransaction
Dequeue the transaction at the head of the service output queue and returns a pointer to it. DequeueOutputTransaction
Enter the region associated with the service. EnterServiceRegion
Enqueue a transaction on either the service or a port input queue. EnqueueInputTransaction
Enqueue a transaction on either the service or a port output queue. EnqueueOutputTransaction
Exit the service region previously entered with EnterServiceRegion. ExitServiceRegion
Return the port ID for a given port handle. GetPortId
Use a TRANSACTION structure to tie up a response message received from the interface. GetTransaction
Look up a port handle given a port ID. LookupPortHandle
Return the first valid transaction at the head of the input queue referenced by the hObject parameter. QueryInputTransactionQueue
Return the first valid transaction at the head of the output queue referenced by the hObject parameter. QueryOutputTransactionQueue
Return a control buffer to the service pool. ReleaseControlBuffer
Return a TRANSACTION structure to the pool. ReleaseTransaction
Request a control buffer from the service pool. RequestControlBuffer
Return a TRANSACTION buffer from the service transaction pool. RequestTransaction
Set the port parameter for the given port to a value given by the caller. SetPortParameter
Retrieve the parameter previously associated with a port by a call to SetPortParameter. GetPortParameter

See Also

TRANSACTION, SERVICEDESC, CONTROLBUFFER, RECEIVEINFO, InstallRtServiceDescriptor, SetRtServiceAttributes, SetRtServiceAttributes, UninstallRtServiceDescriptor, SendMessage, SendRtMessage, SendRtMessageRSVP, SendRtReply, DeliverStatus, DeliverMessage, GetTransaction, RequestControlBuffer, LookupPortHandle