INtime SDK Help
Ports
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. You will receive a compiler warning by default if you use these calls.
The following table lists common operations on ports and the port system calls that do the operations:
| To . . . | Use this system call . . . | |
|---|---|---|
| Service support | Add a service to the operating system | InstallRtServiceDescriptor |
| Remove a service from the operating system | UninstallRtServiceDescriptor | |
| Allow the caller to receive the address of the interface controlled by the service | GetRtServiceAttributes ntxGetRtServiceAttributes | |
| Allow the caller to specify the address of the interface controlled by the service | SetRtServiceAttributes ntxSetRtServiceAttributes | |
| Port object management | Create a message port for access to a given service and return a handle | CreateRtPort CreateRtPortEx ntxCreateRtPort |
| Delete a port | DeleteRtPort ntxDeleteRtPort | |
| Bind an address to a port | BindRtPort ntxBindRtPort | |
| Create a connection between a local port and a remote port | ConnectRtPort ntxConnectRtPort | |
| Enable an application to monitor several ports simultaneously via a sink port | AttachRtPort ntxAttachRtPort | |
| End message forwarding between the specified message port and sink port | DetachRtPort ntxDetachRtPort | |
| Return a structure that provides information about the port object indicated by the supplied handle | GetRtPortAttributes ntxGetRtPortAttributes | |
| Make a heap's memory resources available to one or more message ports | AttachRtHeap | |
| End the association between a heap and a message port | DetachRtHeap | |
| Message transmission | Send a data message from a port to a service and return a transaction ID | SendRtMessage ntxSendRtMessage |
| Send the request phase of a transaction and allocates a storage for the response part of the transaction | SendRtMessageRSVP ntxSendRtMessageRSVP | |
| Send a response message to an earlier received SendRtMessageRSVP message | SendRtReply | |
| Cancel synchronous or asynchronous SendRtMessageRSVP messages | CancelRtTransaction ntxCancelRtTransaction | |
| Receive a message at a port | ReceiveRtMessage ntxReceiveRtMessage | |
| Receive a reply message to an earlier SendRtMessageRSVP transmission | ReceiveRtReply ntxReceiveRtReply | |
| Receive a fragment of an SendRtMessageRSVP data message request | ReceiveRtFragment | |
| Request memory from the system | ntxRequestRtBuffer | |
| Return memory to the system | ntxReleaseRtBuffer |
This shows the order to make port system calls and lists calls that ports frequently use.
Service support
Port object management
Message transmission
Heap object management
A port is the object which allows access to the features provided by INtime services. A process that uses a port object can send messages through the port to an INtime service, or can receive messages through the port from the service. Other operations possible on ports include:
Operations on ports fall into two board categories: setup and message-passing.
When you create a port, you use CreateRtPort. These are the resources you specify when you create a port:
You can attach a heap object to a port to provide a private memory resource. This allows incoming messages to be handled quickly, while controlling the resources used by a service. The RT kernel gives the receiving task a pointer to either the single buffer or to the list descriptor which holds the pointers for all the buffers in the list.
A heap may be attached or detached at any time during the existence of the port. Only one heap may be attached to the port. Use AttachRtHeap and DetachRtHeap.
The heap's particular importance to INtime service is that it provides an efficient way of sharing a memory resource between more than one process, with very low overhead. If a user process allocates its data messages from an heap attached to the port where the messages will be sent, the kernel is very efficient at mapping the data buffers to the service process.
When you delete a port using DeleteRtPort (or by deleting the process which created it), the kernel deletes all messages queued at the port and cancels all outstanding transactions for the port. The kernel deletes message buffers allocated from the port's heap object (if any) and awakens any task waiting at the port with an E_EXIST condition code. If you delete a sink port (described later) that is attached to one or more ordinary ports, the kernel detaches them.
The information below describes the ways a port is identified.
| Identifier | How used |
|---|---|
| Service link | Each port is created for a particular INtime service. Messages sent to a port for a given service can only be interpreted by that service and can only be delivered to a different service by the service it is created for. |
| Port ID | The Port ID identifies the port among all those for a given service on a given instance of the real-time kernel. The port ID is like an address for each port within a service. |
| Hardware interface address | Also known as Host ID. This usually applies to hardware services which manage an interface to a medium such as a bus or network where each attachment is differentiated by its logical address. The format of the hardware address is variable, depending on the medium the service is managing. |
| Generalized address | A generalized address is a structure which combines the Port ID and Hardware Address. It is independent of the operating system in use so it may be used, for example, to identify a port on a network shared by different systems. Use the generalized address rather than the handle to identify the destination or source port of messages. |
| Handle | This is an identifier specific to the INtime kernel. The handle is used as an object reference in the local system and, for example, for cataloging the port in an object directory, to attach a port to a sink port, and to delete a port. |
Messages are the means to convey data and instructions to and from an INtime service. There are certain features common to messages in all services, which are described here.
Although the control and data portions are combined when sent in a message, they are stored differently at the receiving port.
These messages follow the data mailbox model. You can use SendRtMessage to send the message to a port. Use ReceiveRtMessage to receive a message from a port. Sending a message to a port invokes an internal handler in the service which is responsible for handling the message. The precise action performed depends on the design of the service.
By calling ReceiveRtMessage a user process receives the next available message on the port. If no message is currently available the calling thread is put to sleep for the time limit specified in the call, or until a message is delivered to the port by the service.
A message consists of a required control (or header) part and an optional data part. In general a service will use the control part to decide what to do with the data part, but has in general no need to know the contents of the data part. The maximum size of the control part is determined by the service, and is determined when the service is installed.
Data messages may be any size, including zero, and may be contiguous, or made up of a list of buffers. A message with no data part is known as a control message.
A transaction provides a client-server communication model. Clients send request messages to servers and servers send responses back. A server may be the service itself, or an application on a port to which messages may be delivered by this service. This model includes the ability to:
The kernel uses a transaction ID to match responses to requests. The request is delivered to a port using SendRtMessageRSVP, whereupon the service will transmit the message from its interface. On successful transmission, or if transmission was asynchronous, a transaction ID is returned to the caller. The caller uses this transaction ID to make a call to ReceiveRtReply and is put to sleep awaiting a response.
When the service receives a response from the interface, it delivers it to the task waiting in ReceiveRtReply and wakes it up. The service uses the RSVP buffer supplied in the original SendRtMessageRSVP call to deliver the data and a pointer to this buffer is returned to the caller of ReceiveRtReply.
The client supplies a pointer to a response buffer if it expects a data message in response. This buffer is allocated from the client task's job; it is not allocated from the port's heap.
Messages may also be part of a transaction, which consists of a request message and a response message. A transaction is identified by a transaction ID which is associated with the messages in a transaction. Simple messages have no transaction ID. When a request message is sent to a service, a corresponding response message should be expected. Similarly, if an application receives a request message from a service, a response message should be returned to the service in reply.
Transaction pairs provide a client-server communication model. Clients send request messages to servers and servers send responses back. A server may be the service itself, or an application on a port to which messages may be delivered by this service.
The client sends a control/data message that tells the service to perform a process on the data (for example, write it to a disk):
The client task calls SendRtMessageRSVP. The client calls ReceiveRtReply and goes to sleep waiting for the response.
The service delivers the data to the interface and waits for a response (for example, the disk drive returning its status). It then packages the response control and data message and delivers it to the task waiting for the transaction to complete, using the transaction ID supplied by the client when it calls ReceiveRtReply.
To be developed.
This describes the method by which a single thread can receive messages at more than one port, and how a port can be configured to deliver to a single remote address.
Message forwarding allows messages from several connected ports to be received by a single task waiting at a sink port. Sink ports help avoid duplication of code in several tasks. All messages come to the sink port, which forwards them to the appropriate task. The sink port must be on the same host as the receiving task.
The example below shows an intermediate service which is required to process messages from two hardware services. Instead of creating a service task for each port, a sink port is used to receive messages from each of the hardware service ports:
The interfaces described in this section provide the object management interface for the heap object. A heap is created, then buffers may be requested from the heap and subsequently released to the heap. Finally, the heap may be deleted. Two additional interfaces are provided; one to find the size of a buffer allocated from a heap given the heap token and the buffer pointer, and one to interrogate the heap object to determine how much of its resources have been used.
If an application creates a heap, that heap's segment is mapped into the process' virtual segment. No virtual reference is returned to the user, because no direct access of the segment is intended. When buffers are allocated from the segment, the interface library adjusts the buffer offset according to the caller's mapping of the heap segment so that a valid pointer is returned to the caller.
If a heap token is used by a process which did not create it, the heap object must be mapped into the new job's virtual segment and an internal reference of this mapping be kept by the object. This has two purposes: