This module offers both the issue/reclaim model and the read/write model to
send and receive data from drivers.
The client can issue many buffers before reclaiming them.
Buffers are always reclaimed in the order that they were issued.
The client can optionally pass a user argument to issue().
const Stream_INOUT |
|
mode for input & output
#define Stream_INOUT (UInt)2
const Stream_INPUT |
|
mode for input
#define Stream_INPUT (UInt)0
const Stream_OUTPUT |
|
mode for output
#define Stream_OUTPUT (UInt)1
config Stream_A_badMode // module-wide |
|
Assert when read or write on wrong channel
DETAILS
Assert when
read is called and mode =
OUTPUT or
when
write is called and mode =
INPUT
config Stream_A_pendingReclaims // module-wide |
|
Assert when there are more packets to be reclaimed
extern const Assert_Id Stream_A_pendingReclaims;
config Stream_A_syncNonBlocking // module-wide |
|
Assert when ISync is non-blocking but Stream_read/write called
extern const Assert_Id Stream_A_syncNonBlocking;
config Stream_E_noBuffersIssued // module-wide |
|
Error raised when reclaim called but no outstanding buffers issued
extern const Error_Id Stream_E_noBuffersIssued;
DETAILS
Clients can check for this error while calling
reclaim to make
sure they got all their buffers back.
#include <xdc/runtime/Error.h>
#include <ti/sdo/io/Stream.h>
Error_Block eb;
Stream_Handle streamHdl;
SizeT len;
Ptr *bufp;
Error_init(&eb);
do {
len = Stream_reclaim(streamHdl, bufp, NULL, &eb);
}while (!Error_check(&eb));
if (Error_getId == Stream_E_noBuffersIssued) {
....all issues buffers have been reclaimed
}
config Stream_E_noPackets // module-wide |
|
Error raised when there are no packets for IO
extern const Error_Id Stream_E_noPackets;
config Stream_E_notFound // module-wide |
|
Error raised when name not found in IConverter Table and DriverTable
extern const Error_Id Stream_E_notFound;
config Stream_E_timeout // module-wide |
|
Error raised when a timeout occurs during reclaim
config Stream_gate // module-wide |
|
For making the table thread safe
config Stream_maxNameLen // module-wide |
|
Length, in MAUs, of the name field in the table
extern const UInt Stream_maxNameLen;
config Stream_maxRuntimeEntries // module-wide |
|
Max entries that can be added at runtime
extern const UInt Stream_maxRuntimeEntries;
DETAILS
This module requires total number of converters that need
to be added at runtime to be identified at configuration time.
Stream_add() // module-wide |
|
Add to IConverter table at runtime
ARGUMENTS
name
Name of entry
handle
IConverter handle
eb
Error Block
DETAILS
This API is not thread safe. Set
gate parameter
to protect table if called from multiple threads.
Stream_remove() // module-wide |
|
Remove entry from IConverter table at runtime
ARGUMENTS
name
name of entry
eb
error block
DETAILS
This API is not thread safe. Set
gate parameter
to protect table if called from multiple threads.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Stream_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Stream_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Stream_Module_getMask();
// Returns the diagnostics mask for this module
Void Stream_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct Stream_Object Stream_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Stream_Struct Stream_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct Stream_Params {
// Instance config-params structure
// Common per-instance configs
UArg chanParams;
// Channel params for driver if present in IO stack
UInt maxIssues;
// Max outstanding issues
// ISync handle used to signal IO completion
} Stream_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Stream_chanParams // instance |
|
Channel params for driver if present in IO stack
config Stream_maxIssues // instance |
|
Max outstanding issues
config Stream_packetHeap // instance |
|
Heap used to allocate DriverTypes.Packet in dynamic create
config Stream_sync // instance |
|
ISync handle used to signal IO completion
Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
name
name that identifies the IO stack
mode
mode of channel.
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Creates a new Stream instance and sets up the IO stack specified by
name.
The name is usually of the following form "/scale/uart".
The mode is either
INPUT or
OUTPUT.
Instance Deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Stream_abort() // instance |
|
Abort all pending IO
ARGUMENTS
handle
handle of a previously-created Stream instance object
eb
error block
RETURNS
number of buffers aborted
DETAILS
The underlying device connected to stream is idled as a result of
calling abort and all buffers are ready for reclaim().
The client still needs to call
reclaim to get back his
buffers. However the client will NOT block when calling reclaim()
after an abort().
Stream_control() // instance |
|
Send a control command to the driver
ARGUMENTS
handle
handle of a previously-created Stream instance object
cmd
device specific command
cmdArg
command specific arg
eb
error block
Stream_issue() // instance |
|
Issue a buffer to the stream
ARGUMENTS
handle
handle of a previously-created Stream instance object
buf
buffer pointer
size
size of buffer
arg
app arg
eb
error block
DETAILS
This function issues a buffer to the stream for IO. This API is
non-blocking.
Failure of issue() indicates that the stream was not able to accept the
buffer being issued or that there was a error from the underlying
IConverter or IDriver. Note that the error could be driver specific.
If issue() fails because of an underlying driver problem
abort should be called before attempting more I/O through the
stream.
The interpretation of the logical size of a buffer, is
direction dependent.
For a stream opened in
DriverTypes.OUTPUT mode, the logical size
of the buffer indicates the number of minimum addressable units of of
data it contains.
For a stream opened in
DriverTypes.INPUT mode, the logical size
of a buffer indicates the number of minimum addressable units being
requested by the client. In either case, the logical size of the buffer
must be less than or equal to the physical size of the buffer.
issue() is used in conjunction with
reclaim. The issue() call
sends a buffer to a stream, and reclaim() retrieves a buffer
from a stream. In normal operation each issue() call is followed by an
reclaim() call.
Short bursts of multiple issue() calls can be made without an
intervening reclaim() call followed by short bursts of reclaim() calls,
but over the life of the stream issue() and reclaim() must be called
the same number of times. The number of issue() calls can exceed the
number of reclaim() calls by
maxIssues.
The client argument is not interpreted by Stream or the underlying
modules, but is offered as a service to the stream client. All compliant
device drivers preserve the value of arg and maintain its association
with the data that it was issued with. arg provides a method for a
client to associate additional information with a particular buffer of
data. The arg is returned during reclaim().
Stream_prime() // instance |
|
Prime an OUTPUT stream instance
ARGUMENTS
handle
handle of a previously-created Stream instance object
buf
buffer pointer
arg
app arg
eb
error block
DETAILS
This API facilitates buffering of an output channel. Consider a
task that constantly gets data from input channel and sends to an
output channel. To start with it may want to issue buffers to the
input channel and output channel to enable double buffering.
For an input channel there is no problem. For an output channel however
the buffer data is sent out through the peripheral and in the case of a
heterogenous system, the data will be sent to the other processor.
In such cases where the driver cannot handle dummy buffers,
Stream_prime can be used to make buffers available instantly for
reclaim without actually sending the buffers to the driver.
This API is non-blocking.
The primary use of prime() is used when applications want to prime
an output channel at startup, without sending data to the driver.
This allows them to reclaim and issue in their task.
Failure of prime() indicates that the stream was not able to accept the
buffer being issued due to un-avaibailibity of IO packets.
The client argument is not interpreted by Stream.
Stream_read() // instance |
|
Read data from a stream
ARGUMENTS
handle
handle of a previously-created Stream instance object
bufp
buffer pointer
size
size of buffer
timeout
timeout in microseconds
eb
error block
RETURNS
size transferred
DETAILS
Equivalent to an issue/reclaim pair for a instance with
mode = DriverTypes.INPUT. This call is synchronous and the buffer
has data upon return from this API.
Stream_reclaim() // instance |
|
Reclaim a buffer that was previously issued by calling issue
ARGUMENTS
handle
handle of a previously-created Stream instance object
pbufp
returned buffer pointer
timeout
timeout in microseconds
parg
pointer to client arg. Can be null.
eb
error block
RETURNS
size transferred
DETAILS
reclaim() is used to request a buffer back from a stream.
If a stream was created in
DriverTypes.OUTPUT mode, then
reclaim() returns a processed buffer, and size is zero.
If a stream was opened in
DriverTypes.INPUT mode, reclaim()
returns a full buffer, and size is the number of minimum addressable
units of data in the buffer.
reclaim() blocks until a buffer can be returned to the caller, or until
a timeout occurs.
Failure of reclaim() indicates that no buffer was returned to
the client. Therefore, if reclaim() fails, the client should
not attempt to de-reference pbufp, since it is not guaranteed to contain
a valid buffer pointer.
reclaim() is used in conjunction with
issue to operate
a stream. The issue() call sends a buffer to a stream, and
reclaim() retrieves a buffer from a stream. In normal operation
each issue call is followed by an reclaim call.
Short bursts of multiple issue() calls can be made without an
intervening reclaim() call followed by short bursts of reclaim() calls,
but over the life of the stream issue() and reclaim() must be called
the same number of times. The number of issue() calls can exceed the
number of reclaim() calls by
maxIssues.
A reclaim() call should not be made without at least one
outstanding issue() call. Calling reclaim() with no
outstanding issue() calls results in an error
E_noBuffersIssued
reclaim() only returns buffers that were passed in using issue(). It
also returns the buffers in the same order that they were issued.
reclaim() returns the size transferred in case of success.
It returns zero when an error is caught. In case of timeout, the error
is
E_timeout.
Stream_write() // instance |
|
Write data to a stream
ARGUMENTS
handle
handle of a previously-created Stream instance object
bufp
buffer pointer
size
size of buffer
timeout
timeout in microseconds
eb
error block
RETURNS
size transferred
DETAILS
Equivalent to an issue/reclaim pair for a instance with
mode = DriverTypes.OUTPUT.
This call is synchronous and the driver has finished processing the
buffer upon return from this API.
Instance Built-Ins |
|
Int Stream_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
const Stream.INOUT |
|
mode for input & output
XDCscript usage |
meta-domain |
C SYNOPSIS
const Stream.INPUT |
|
mode for input
XDCscript usage |
meta-domain |
C SYNOPSIS
const Stream.OUTPUT |
|
mode for output
XDCscript usage |
meta-domain |
C SYNOPSIS
metaonly struct Stream.BasicView |
|
XDCscript usage |
meta-domain |
var obj = new Stream.BasicView;
obj.label = String ...
obj.maxIssues = UInt ...
obj.issued = UInt ...
obj.ready = UInt ...
obj.mode = String ...
obj.userSuppliedSync = Bool ...
config Stream.A_badMode // module-wide |
|
Assert when read or write on wrong channel
XDCscript usage |
meta-domain |
msg: "A_badMode: Bad Mode"
};
DETAILS
Assert when
read is called and mode =
OUTPUT or
when
write is called and mode =
INPUT
C SYNOPSIS
config Stream.A_pendingReclaims // module-wide |
|
Assert when there are more packets to be reclaimed
XDCscript usage |
meta-domain |
msg: "A_pendingReclaims: Packets issued but not reclaimed"
};
C SYNOPSIS
config Stream.A_syncNonBlocking // module-wide |
|
Assert when ISync is non-blocking but Stream_read/write called
XDCscript usage |
meta-domain |
msg: "A_syncNonBlocking: ISync should have blocking quality"
};
C SYNOPSIS
config Stream.E_noBuffersIssued // module-wide |
|
Error raised when reclaim called but no outstanding buffers issued
XDCscript usage |
meta-domain |
msg: "E_noBuffersIssued: No outstanding buffers"
};
DETAILS
Clients can check for this error while calling
reclaim to make
sure they got all their buffers back.
#include <xdc/runtime/Error.h>
#include <ti/sdo/io/Stream.h>
Error_Block eb;
Stream_Handle streamHdl;
SizeT len;
Ptr *bufp;
Error_init(&eb);
do {
len = Stream_reclaim(streamHdl, bufp, NULL, &eb);
}while (!Error_check(&eb));
if (Error_getId == Stream_E_noBuffersIssued) {
....all issues buffers have been reclaimed
}
C SYNOPSIS
config Stream.E_noPackets // module-wide |
|
Error raised when there are no packets for IO
XDCscript usage |
meta-domain |
msg: "E_noPackets: No packets available. maxIssues is %d"
};
C SYNOPSIS
config Stream.E_notFound // module-wide |
|
Error raised when name not found in IConverter Table and DriverTable
XDCscript usage |
meta-domain |
msg: "E_notFound: %s name not found"
};
C SYNOPSIS
config Stream.E_timeout // module-wide |
|
Error raised when a timeout occurs during reclaim
XDCscript usage |
meta-domain |
msg: "E_timeout: Timeout"
};
C SYNOPSIS
config Stream.gate // module-wide |
|
For making the table thread safe
XDCscript usage |
meta-domain |
C SYNOPSIS
config Stream.maxNameLen // module-wide |
|
Length, in MAUs, of the name field in the table
XDCscript usage |
meta-domain |
Stream.maxNameLen = UInt 16;
C SYNOPSIS
config Stream.maxRuntimeEntries // module-wide |
|
Max entries that can be added at runtime
XDCscript usage |
meta-domain |
Stream.maxRuntimeEntries = UInt 0;
DETAILS
This module requires total number of converters that need
to be added at runtime to be identified at configuration time.
C SYNOPSIS
metaonly config Stream.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config Stream.rovViewInfo // module-wide |
|
XDCscript usage |
meta-domain |
metaonly config Stream.tableSection // module-wide |
|
Section name used to place the IConverter table
XDCscript usage |
meta-domain |
Stream.tableSection = String null;
metaonly Stream.addMeta() // module-wide |
|
Add to IConverter table at configuration time
XDCscript usage |
meta-domain |
ARGUMENTS
name
name of entry
handle
IConverter handle
Instance Config Parameters |
|
XDCscript usage |
meta-domain |
var params = new Stream.Params;
// Instance config-params object
params.chanParams = UArg null;
// Channel params for driver if present in IO stack
params.maxIssues = UInt 2;
// Max outstanding issues
params.packetSection = String null;
// ISync handle used to signal IO completion
config Stream.chanParams // instance |
|
Channel params for driver if present in IO stack
XDCscript usage |
meta-domain |
var params = new Stream.Params;
...
params.chanParams = UArg null;
C SYNOPSIS
config Stream.maxIssues // instance |
|
Max outstanding issues
XDCscript usage |
meta-domain |
var params = new Stream.Params;
...
params.maxIssues = UInt 2;
C SYNOPSIS
config Stream.packetHeap // instance |
|
Heap used to allocate DriverTypes.Packet in dynamic create
XDCscript usage |
meta-domain |
var params = new Stream.Params;
...
C SYNOPSIS
config Stream.sync // instance |
|
ISync handle used to signal IO completion
XDCscript usage |
meta-domain |
var params = new Stream.Params;
...
C SYNOPSIS
metaonly config Stream.packetSection // instance |
|
Section name used to place DriverTypes.Packet
XDCscript usage |
meta-domain |
var params = new Stream.Params;
...
params.packetSection = String null;
DETAILS
Default of null results in no explicit section placement.
Instance Creation |
|
XDCscript usage |
meta-domain |
var params =
new Stream.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Stream.create(String name, UInt mode, params);
// Create an instance-object
ARGUMENTS
name
name that identifies the IO stack
mode
mode of channel.
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Creates a new Stream instance and sets up the IO stack specified by
name.
The name is usually of the following form "/scale/uart".
The mode is either
INPUT or
OUTPUT.