OSMMsgGetReqBuf(D3i2o)

OSMMsgGetReqBuf -- acquire a message frame from the inbound queue

Synopsis

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

I2O_MESSAGE_FRAME  *OSMMsgGetReqBuf(int iop, uint_t wait, uint_t flags)

Description

OSMMsgGetReqBuf is the only acceptable way of acquiring a message frame from the inbound queue (that is, a message sent to the IOP).

The memory returned may be a genuine frame from the IOP's inbound FIFO, or it may be a buffer from local memory. This is implementation-dependent, and the OSM should make no assumptions as to which memory type it has acquired. It is the transport layer's responsibility to provide a buffer that the OSM may treat as normal memory, free from alignment, bit access, or read/write ordering constraints.

If the OSM no longer needs the message frame, it should be freed using OSMMsgFreeReqBuf. (The transport layer will deal with converting the message to an i2oUtilNop message if required.)

Arguments

iop

Global IOP number known to the message layer.

flags

Valid flags are:

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

wait

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

Return values

A pointer to the buffer on success, or NULL on failure. The transport layer will already have waited or retried as directed by wait and flags.

Usage

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), OSMMsgSend(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.