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:

• Execute I/O instructions from any process.
• Install interrupt handlers and process interrupts in a hierarchical fashion based on interrupt priority.
• Support DMA through I/O operations and access to the physical address of any memory reference.

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

• Flexibility: The messaging interface provides flexibility which is lacking in a standard "file-service" I/O driver,
• Organization: These features are organized to present a standard interface to any process and to provide an interchangeable service (for example, to upgrade a hardware interface only the service needs to be replaced, the application using it does not),
• Queuing support: The queuing requirements of a hardware device driver are mostly done by the port object, and other queuing mechanisms are supported,
• Debug support: The port object is recognized by both debuggers supplied with INtime, reducing the debugging effort of writing a driver.

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:

• the set of messages the service processes, and
• the way the service processes each message.

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:

• Simple user process: sends messages to and/or receives messages from a service without any association between send and receive message,
• Client user process: sends requests to a service and expects responses to those requests,
• Server user process: receives request messages from a local service and processes them before returning response messages.

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.

• Hardware service: usually controls an interface which generates interrupts or clock-based events. The interface object actually may be anything other than a port object. This category of service typically provides low-level access to a hardware device.
• Intermediate service: always receives events from a port object provided by another service, either a hardware service or another intermediate service. This category of service is used to add higher-level functionality to a hardware service.

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:

• When a port is created, a reference to a service descriptor is associated with it. A port may only provide access to one single service.
• The service descriptor references service handler subroutines which may be referenced by more than one service descriptor. This allows a single service code module to handle multiple interfaces, for example a multi-channel serial controller service may be implemented as a single code module with one service descriptor for each hardware interface.
• Events from the interface are handled by the service thread. This service thread calls the service handler service to process the event. There is one service task created for each service descriptor installed.
• The parts of the service provided by the implementer are the service descriptor and the service handlers.

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:

• Design a set of messages used by the service, and decide on the action that each message provokes.
• Decide which features the service uses and define the SERVICEDESC structure contents accordingly.

  Note:   The SERVICEDESC structure contains all the configuration information needed to run the service. It must be initialized before installation so that the kernel can configure the internal resources ready for use.

• Decide which parameters (if any) may be read and modified dynamically, using SetRtServiceAttributes.
• Write the handlers to carry out the design actions.
• Write a header file which can be included by users developing applications which use the service.
• Compile your code and link with the service library, RTSERV.LIB.

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:

• Stuffs the control message into the control buffer. A pointer to the control message passed by the user is passed to the SendMessage handler.
• Initiates the transmission of the message (even if this means just putting it on an output queue for handling by the service thread later).
• Returns the appropriate status code. This code is returned to the caller of the primitive.
  • E_SEND_NOT_COMPLETE, if the transmission is not yet complete. This code is not returned to the caller, but instead causes the RT kernel to put the calling thread to sleep until the transmit operation has completed.
  • E_OK if the transmission completed.
  • OTHER if the transmission failed.

  Part of the service thread function is to handle transmission completion events. The second part of transmission handling is done here.

• When a previously-started transmit operation completes, a call must be made to DeliverStatus with the transaction pointer and the 16-bit transmission status code as parameters. If the transmission was successful, the value E_OK should be used, else the value E_TRANSMISSION should normally be used. If the original call to SendRtMessage (etc.) was asynchronous, a status message is sent to the port for receiving by the user later. If the original operation was synchronous the status code sent to DeliverStatus is returned to the caller of SendRtMessage (etc.).

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.

• Messages received originate at the service interface.
• The service must allocate a control buffer by calling RequestControlBuffer and fill in the appropriate fields.
• The destination port must be determined. The handle may be found from the port ID using LookupPortHandle.
• If the message can be delivered immediately, this can be done by calling DeliverMessage.
• If the message is part of an existing transaction (i.e. it is the response part of a request-response transaction) then the transaction buffer may be found by calling GetTransaction, using the transaction ID and port ID and (if applicable) the remote address of the host where the current message originated. The control buffer should be linked to the transaction buffer by setting the InControlMessage field of the Transaction buffer to the pointer to the control buffer.

• Processing an input message

  When an input message has been received at the interface (with good or bad status), the actions required differ dependent upon whether the newly-arrived message is a response to a previous request, or a new request, or a transaction-less message.

• Response message

  In this case a transaction structure will already exist for this message. The service:

  1. Looks up the port handle from the destination port ID of this message.
  2. Looks up the transaction structure by calling GetTransaction with the port handle, transaction ID and remote source address. These last two fields should come from the message.
  3. Requests and fills a control buffer with the control message, and reference the data part by setting the lpData, dwDataLength and wFlags fields of the control buffer. Link this buffer to the lpInControl field of the transaction.
  4. Calls DeliverTransaction, and stops.

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