OSMMsgSend(D3i2o)

OSMMsgSend -- send message to an IOP

Synopsis

#include <sys/types.h>
#include <i2o/i2omsg.h>
#include <i2o/common.h>

int OSMMsgSend(int IopNum, I2O_MESSAGE_FRAME *msg, uint_t wait, uint_t flags)

Description

OSMMsgSend is used to send a message to a target IOP.

Arguments

IopNum

The global number of the IOP which supplied the message frame.

msg

A pointer to the message frame.

flags

Valid flags are:

I2OTRANS_NOSLEEP: The function may not sleep while acquiring memory.
I2OTRANS_SLEEP: The function may sleep while acquiring memory.

All other flags bits are reserved and must be set to 0.

wait

Time, in microseconds, that the system should wait for an IOP to supply a buffer.

Return values

SUCCESS: The message has been delivered to the IOP. Freeing of the message frame is handled by the transport layer.
EINVAL: Invalid argument (such as an invalid IOP number).
ENOMEM: Failed to obtain the memory required.

Usage

OSMMsgSend is the only valid method for sending a message to a target IOP. All messages that require a reply have an InitiatorContext field. This field should contain one of the cookies obtained from OSMMsgRegister. When the target IOP replies, it calls the OSM's callback function that corresponds to the cookie.

On failure, the message frame has not been freed.

Context and synchronization constraints

If flags is set to I2OTRANS_NOSLEEP, the context may be non-blockable, initialization, or interrupt.

If flags is set to I2OTRANS_SLEEP, the context may be user.

Hardware applicability

All

Version applicability

i2omsg: in HDK Technical Reference 2

Differences between versions

None

References

Intro(D3i2o), kmem_alloc(D3), OSMMsgFreeReqBuf(D3i2o), OSMMsgRegister(D3i2o), OSMMsgGetReqBuf(D3i2o)

Notices

Characteristics of i2otrans

i2otrans is the I2O single-segment PCI transport. By default, this driver satisfies OSMMsgGetReqBuf requests using system memory obtained using kmem_alloc(D3). i2otrans obtains a real message frame from the inbound FIFO during OSMMsgSend, and copies the message data into it before posting it back.

NOTE: This default behavior may change. Writers of OSMs should not rely on OSMMsgGetReqBuf using system memory.

The i2otrans driver ignores the wait parameter when using kmem_alloc to obtain a buffer, and maps I2OTRANS_NOSLEEP to KM_NOSLEEP to specify whether the request should sleep. This now follows the normal kmem_alloc sleep/nosleep characteristics.

In instances where the driver must obtain a message frame from the inbound FIFO, it uses wait and the sleep flag as follows:

i2otrans attempts to obtain a message frame.
If wait is non-zero, i2otrans examines the sleep flag, and either delays (sleeps) or busy waits (spins) for 100ms.
At the end of the 100ms period it again attempts to get a message frame from the inbound FIFO. If this fails, it continually waits for 100ms and tries again until it either succeeds, or the cumulative delay exceeds the wait value.
If wait is non-zero, the minimum delay is 100ms. The actual period may be up to 100ms shorter than specified.