module ti.sysbios.io.GIO

General Purpose IO Manager

The GIO Manager offers both the issue/reclaim model and the read/write model to send and receive data from drivers that implement the IOM interface as provided in ti/sysbios/io/iom.h. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/io/GIO.xdc
#include <ti/sysbios/io/GIO.h>
Functions
Int 
Int 
GIO_addDevice// This API has been deprecated. Use DEV_create()(String name, Ptr fxns, GIO_InitFxn initFxn, Int devid, Ptr params);
Void
Int 
Void
Void
Int 
Int 
GIO_issue// Issue a buffer to the stream(GIO_Handle handle, Ptr buf, SizeT size, UArg arg);
Void
Int 
GIO_prime// Prime an OUTPUT stream instance(GIO_Handle handle, Ptr buf, SizeT size, UArg arg);
Int 
GIO_read// Synchronous read command(GIO_Handle handle, Ptr buf, SizeT *pSize);
Int 
Int 
Int 
GIO_submit// Submit an IO job to the mini-driver(GIO_Handle handle, UInt cmd, Ptr buf, SizeT *pSize, GIO_AppCallback *appCallback);
Int 
GIO_write// Synchronous write command(GIO_Handle handle, Ptr buf, SizeT *pSize);
Functions common to all target instances
Functions common to all target modules
Defines
#define
#define
#define
Typedefs
typedef struct
typedef GIO_Object *
typedef Void 
typedef enum
typedef struct
typedef struct
typedef struct
typedef Void 
Constants
extern const Assert_Id 
extern const Int 
extern const Error_Id 
extern const Error_Id 
 
DETAILS
The GIO Manager offers both the issue/reclaim model and the read/write model to send and receive data from drivers that implement the IOM interface as provided in ti/sysbios/io/iom.h.
In the issue/reclaim model, the client calls issue when he has a buffer of data. issue() is non-blocking and returns -- it simply submits the buffer to the driver for I/O. The client calls reclaim to get the buffer back. A call to reclaim() may block. Upon return from reclaim(), the client can re-use the buffer.
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(). This argument can be retrieved with reclaim().
In the read/write model, clients will call read or write to send/receive data. Here the client may block until buffer is ready or a timeout occurs.
The GIO module also provides control to send down driver specific control commands. The abort function can be used to abort any pending I/O.
The ti.sysbios.io.DEV module maintains a name table of IOM drivers. This table is used by GIO to create an IO stack. The name passed to create is usually of the form "/uart". This name may correspond to the following IO stack.
GIO Instance
| v
IOM Instance (/uart)
The GIO module uses the xdc.runtime.knl.Sync module for synchronization. GIO will call xdc.runtime.knl.Sync.signal when I/O completes and xdc.runtime.knl.Sync.wait to wait for I/O.
By default the I/O manager will create a semaphore for synchronization if no sync handle is passed to create.
 
const GIO_INOUT

mode for input & output

C synopsis target-domain
#define GIO_INOUT (UInt)0x3
 
 
const GIO_INPUT

mode for input

C synopsis target-domain
#define GIO_INPUT (UInt)0x1
 
 
const GIO_OUTPUT

mode for output

C synopsis target-domain
#define GIO_OUTPUT (UInt)0x2
 
 
enum GIO_Model

model for IO channel

C synopsis target-domain
typedef enum GIO_Model {
    GIO_Model_STANDARD,
    // used for read, write, submit
    GIO_Model_ISSUERECLAIM
    // used for issue, reclaim, prime
} GIO_Model;
 
 
typedef GIO_InitFxn

Init function type definition

C synopsis target-domain
typedef Void (*GIO_InitFxn)();
 
 
typedef GIO_TappCallBack

application callback function used with GIO_submit()

C synopsis target-domain
typedef Void (*GIO_TappCallBack)(Ptr,Int,Ptr,SizeT);
 
 
struct GIO_AppCallback

Application Callback Structure

C synopsis target-domain
typedef struct GIO_AppCallback {
    GIO_TappCallBack fxn;
    Ptr arg;
} GIO_AppCallback;
 
DETAILS
Used with GIO_submit() for asynchronous callback.
 
config GIO_A_badModel  // module-wide

Asserted in GIO_read(), GIO_write() if I/O model is not STANDARD or in GIO_issue(), GIO_reclaim(), or GIO_prime() if the I/O model is not ISSUERECLAIM

C synopsis target-domain
extern const Assert_Id GIO_A_badModel;
 
 
config GIO_E_createFailed  // module-wide

Error raised when driver's mdCreateChan() call fails

C synopsis target-domain
extern const Error_Id GIO_E_createFailed;
 
 
config GIO_E_notFound  // module-wide

Error raised when name not found in DeviceTable

C synopsis target-domain
extern const Error_Id GIO_E_notFound;
 
 
config GIO_deviceTableSize  // module-wide

This configuration parameter has been deprecated. Use DEV.tableSize

C synopsis target-domain
extern const Int GIO_deviceTableSize;
 
 
GIO_addDevice()  // module-wide

This API has been deprecated. Use DEV_create()

C synopsis target-domain
Int GIO_addDevice(String name, Ptr fxns, GIO_InitFxn initFxn, Int devid, Ptr params);
 
 
GIO_removeDevice()  // module-wide

This API has been deprecated. Use DEV_match() and DEV_delete()

C synopsis target-domain
Int GIO_removeDevice(String name);
 
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId GIO_Module_id();
// Get this module's unique id
 
Bool GIO_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle GIO_Module_heap();
// The heap from which this module allocates memory
 
Bool GIO_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 GIO_Module_getMask();
// Returns the diagnostics mask for this module
 
Void GIO_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct GIO_Object GIO_Object;
// Opaque internal representation of an instance object
 
typedef GIO_Object *GIO_Handle;
// Client reference to an instance object
 
typedef struct GIO_Struct GIO_Struct;
// Opaque client structure large enough to hold an instance object
 
GIO_Handle GIO_handle(GIO_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
GIO_Struct *GIO_struct(GIO_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct GIO_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Ptr chanParams;
    // channel parameters
    GIO_Model model;
    // I/O model
    Int numPackets;
    // Number of packets to use for asynchronous I/O
    Ptr packets;
    // The address of the buffer used for IOM packets
    ISync_Handle sync;
    // ISync handle used to signal IO completion
    UInt timeout;
    // For blocking calls. Default is BIOS_WAIT_FOREVER
} GIO_Params;
 
Void GIO_Params_init(GIO_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config GIO_Params.chanParams  // instance

channel parameters

C synopsis target-domain
struct GIO_Params {
      ...
    Ptr chanParams;
 
DETAILS
The chanParams parameter is a pointer that may be used to pass device or domain-specific arguments to the mini-driver. The contents at the specified address are interpreted by the mini-driver in a device-specific manner.
 
config GIO_Params.model  // instance

I/O model

C synopsis target-domain
struct GIO_Params {
      ...
    GIO_Model model;
 
DETAILS
Set the model to STANDARD to use read(), write() and submit() APIs. Set the model to ISSUERECLAIM to use issue(), reclaim(), and prime() APIs.
The default for this parameter is STANDARD.
 
config GIO_Params.numPackets  // instance

Number of packets to use for asynchronous I/O

C synopsis target-domain
struct GIO_Params {
      ...
    Int numPackets;
 
 
config GIO_Params.packets  // instance

The address of the buffer used for IOM packets

C synopsis target-domain
struct GIO_Params {
      ...
    Ptr packets;
 
DETAILS
If set to 'null', the packets will be allocated from the heap during runtime, otherwise the user may set this to a buffer of their creation to be used for the IOM packets.
The packets will be split into ti.sysbios.io.GIO.numPackets each the size of IOM_Packet.
Please note that if the packets is user supplied, then it is the user's responsibility to ensure that it is aligned properly and is also large enough to contain ti.sysbios.io.GIO.numPackets number of IOM_Packet packets. The size of packets buffer, if provided, should be
      sizeof(IOM_Packet) * numPackets
Example:
  #define NUMPACKETS  2
  IOM_Packet inPackets[NUMPACKETS];

  GIO_Params params;

  GIO_Params_init(&params);
  params.numPackets = NUMPACKETS;
  params.packets = inPackets;
 
config GIO_Params.sync  // instance

ISync handle used to signal IO completion

C synopsis target-domain
struct GIO_Params {
      ...
    ISync_Handle sync;
 
 
config GIO_Params.timeout  // instance

For blocking calls. Default is BIOS_WAIT_FOREVER

C synopsis target-domain
struct GIO_Params {
      ...
    UInt timeout;
 
Runtime Instance Creation

C synopsis target-domain
GIO_Handle GIO_create(String name, UInt mode, const GIO_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void GIO_construct(GIO_Struct *structP, String name, UInt mode, const GIO_Params *params, Error_Block *eb);
// 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
An application calls GIO_create to create a GIO_Obj object and open a communication channel. This function initializes the I/O channel and opens the lower-level device driver channel. The GIO_create call also creates the synchronization objects it uses and stores them in the GIO_Obj object.
The name argument is the name specified for the device when it was created in the configuration or at runtime.
The mode argument specifies the mode in which the device is to be opened. This may be IOM_INPUT, IOM_OUTPUT, or IOM_INOUT.
If the status returned by the device is non-NULL, a status value is placed at the address specified by the status parameter.
The GIO_create call allocates a list of IOM_Packet items as specified by the numPackets member of the params structure and stores them in the GIO_Obj object it creates.
Instance Deletion

C synopsis target-domain
Void GIO_delete(GIO_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void GIO_destruct(GIO_Struct *structP);
// Finalize the instance object inside the provided structure
 
GIO_abort()  // instance

Abort all pending IO

C synopsis target-domain
Int GIO_abort(GIO_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
An application calls GIO_abort to abort all input and output from the device. When this call is made, all pending calls are completed with a status of GIO_ABORTED. An application uses this call to return the device to its initial state. Usually this is done in response to an unrecoverable error at the device level.
GIO_abort returns IOM_COMPLETED upon successfully aborting all input and output requests. If an error occurs, the device returns a negative value. The list of error values are defined in the ti/sysbios/io/iom.h file.
A call to GIO_abort results in a call to the mdSubmit function of the associated mini-driver. The IOM_ABORT command is passed to the mdSubmit function. The mdSubmit call is typically a blocking call, so calling GIO_abort can result in the thread blocking.
If using ISSUERECLAIM IO model, the the underlying device connected to stream is idled as a result of calling abort and all buffers are ready for reclaim(). The client needs to call reclaim to get back the buffers. However the client will NOT block when calling reclaim() after an abort().
 
GIO_control()  // instance

Send a control command to the driver

C synopsis target-domain
Int GIO_control(GIO_Handle handle, UInt cmd, Ptr args);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
cmd — device specific command
args — pointer to device-specific arguments
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
An application calls GIO_control to configure or perform control functionality on the communication channel.
The cmd parameter may be one of the command code constants listed in ti/sysbios/io/iom.h. A mini-driver may add command codes for additional functionality.
The args parameter points to a data structure defined by the device to allow control information to be passed between the device and the application. This structure can be generic across a domain or specific to a mini-driver. In some cases, this argument may point directly to a buffer holding control data. In other cases, there may be a level of indirection if the mini-driver expects a data structure to package many components of data required for the control operation. In the simple case where no data is required, this parameter may just be a predefined command value.
GIO_control returns IOM_COMPLETED upon success. If an error occurs, the device returns a negative value. For a list of error values, see ti/sysbios/io/iom.h. A call to GIO_control results in a call to the mdControl function of the associated mini-driver. The mdControl call is typically a blocking call, so calling GIO_control can result in blocking.
 
GIO_flush()  // instance

Drain output buffers and discard any pending input

C synopsis target-domain
Int GIO_flush(GIO_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
An application calls GIO_flush to flush the input and output channels of the device. All input data is discarded; all pending output requests are completed. When this call is made, all pending input calls are completed with a status of IOM_FLUSHED, and all output calls are completed routinely.
This call returns IOM_COMPLETED upon successfully flushing all input and output. If an error occurs, the device returns a negative value. For a list of error values, see ti/sysbios/io/iom.h.
A call to GIO_flush results in a call to the mdSubmit function of the associated mini-driver. The IOM_FLUSH command is passed to the mdSubmit function. The mdSubmit call is typically a blocking call, so calling GIO_flush can result in the thread blocking while waiting for output calls to be completed.
 
GIO_issue()  // instance

Issue a buffer to the stream

C synopsis target-domain
Int GIO_issue(GIO_Handle handle, Ptr buf, SizeT size, UArg arg);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
buf — buffer pointer
size — size of buffer
arg — application arg
RETURNS
IOM_COMPLETED on success, < 0 on failure
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 driver. 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 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 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 IO 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().
 
GIO_prime()  // instance

Prime an OUTPUT stream instance

C synopsis target-domain
Int GIO_prime(GIO_Handle handle, Ptr buf, SizeT size, UArg arg);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
buf — buffer pointer
size — size of buffer
arg — app arg
RETURNS
IOM_COMPLETED on success, < 0 on failure
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, IO_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 IO.
 
GIO_read()  // instance

Synchronous read command

C synopsis target-domain
Int GIO_read(GIO_Handle handle, Ptr buf, SizeT *pSize);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
buf — buffer pointer
pSize — pointer to size of buffer (INPUT/OUTPUT parameter)
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
An application calls GIO_read to read a specified number of MADUs (minimum addressable data units) from the communication channel.
The buf parameter points to a device-defined data structure for passing buffer data between the device and the application. This structure may be generic across a domain or specific to a single mini-driver. In some cases, this parameter may point directly to a buffer that holds the read data. In other cases, this parameter may point to a structure that packages buffer information, size, offset to be read from, and other device-dependent data. For example, for video capture devices this structure may contain pointers to RGB buffers, their sizes, video format, and a host of data required for reading a frame from a video capture device. Upon a successful read, this argument points to the returned data.
The pSize parameter points to the size of the buffer or data structure pointed to by the buf parameter. When the function returns, this parameter points to the number of MADUs read from the device. This parameter is relevant only if the buf parameter points to a raw data buffer. In cases where it points to a device-defined structure it is redundant -- the size of the structure is known to the mini-driver and the application. At most, it can be used for error checking.
GIO_read returns IOM_COMPLETED upon successfully reading the requested number of MADUs from the device. If an error occurs, the device returns a negative value. For a list of error values, see ti/sybios/io/iom.h.
A call to GIO_read results in a call to the mdSubmit function of the associated mini-driver. The IOM_READ command is passed to the mdSubmit function. The mdSubmit call is typically a blocking call, so calling GIO_read can result in the thread blocking.
 
GIO_reclaim()  // instance

Reclaim a buffer that was previously issued by calling issue

C synopsis target-domain
Int GIO_reclaim(GIO_Handle handle, Ptr *pBuf, SizeT *pSize, UArg *pArg);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
pBuf — returned buffer pointer
pSize — pointer to size of buffer (OUTPUT parameter)
pArg — pointer to client arg. Can be null.
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
reclaim() is used to request a buffer back from a stream.
If a stream was created in OUTPUT mode, then reclaim() returns a processed buffer, and size is zero. If a stream was opened in INPUT mode, reclaim() returns a full buffer, and size is the number of minimum addressable units of data in the buffer.
reclaim() calls Sync_wait() with the timeout specified when the channel was created. For the default SyncSem, 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 pBuf, 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.
 
GIO_submit()  // instance

Submit an IO job to the mini-driver

C synopsis target-domain
Int GIO_submit(GIO_Handle handle, UInt cmd, Ptr buf, SizeT *pSize, GIO_AppCallback *appCallback);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
cmd — driver specific packet command
buf — buffer pointer
pSize — pointer to size of buffer (INPUT/OUTPUT parameter)
appCallBack — pointer to application callback structure
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
GIO_submit is not typically called by applications. Instead, it is used internally and for user-defined extensions to the GIO module.
The cmd parameter is IOM_READ, IOM_WRITE, IOM_ABORT or IOM_FLUSH when used internally. A mini driver may add command codes for additional functionality.
The bufp parameter points to a device-defined data structure for passing buffer data between the device and the application. This structure may be generic across a domain or specific to a single mini-driver. In some cases, this parameter may point directly to a buffer that holds the data. In other cases, this parameter may point to a structure that packages buffer information, size, offset to be read from, and other device-dependent data.
The pSize parameter points to the size of the buffer or data structure pointed to by the bufp parameter. When the function returns, this parameter points to the number of MADUs transferred to or from the device. This parameter is relevant only if the bufp parameter points to a raw data buffer. In cases where it points to a device-defined structure it is redundant -- the size of the structure is known to the mini-driver and the application. At most, it can be used for error checking.
The appCallback parameter points to either a callback structure that contains the callback function to be called when the request completes. queued request is completed, the callback routine (if specified) is invoked (i.e. blocking). If the appCallback parameter is NULL, then the call to GIO_submit() will be synchronous and will not return until IO is complete (or an error occurs).
GIO_submit returns IOM_COMPLETED upon successfully carrying out the requested functionality. If the request is queued, then a status of IOM_PENDING is returned. If an error occurs, the device returns a negative value. For a list of error values, see ti/sysbios/io/iom.h.
A call to GIO_submit results in a call to the mdSubmit function of the associated mini-driver. The specified command is passed to the mdSubmit function.
 
GIO_write()  // instance

Synchronous write command

C synopsis target-domain
Int GIO_write(GIO_Handle handle, Ptr buf, SizeT *pSize);
 
ARGUMENTS
handle — handle of a previously-created GIO instance object
buf — buffer pointer
pSize — pointer to size of buffer (INPUT/OUTPUT parameter)
RETURNS
IOM_COMPLETED on success, < 0 on failure
DETAILS
An application calls GIO_write to write a specified number of MADUs (minimum addressable data units) from the communication channel.
The buf parameter points to a device-defined data structure for passing buffer data between the device and the application. This structure may be generic across a domain or specific to a single mini-driver. In some cases, this parameter may point directly to a buffer that holds the write data. In other cases, this parameter may point to a structure that packages buffer information, size, offset to be write from, and other device-dependent data. For example, for video capture devices this structure may contain pointers to RGB buffers, their sizes, video format, and a host of data required for reading a frame from a video capture device.
The pSize parameter points to the size of the buffer or data structure pointed to by the buf parameter. When the function returns, this parameter points to the number of MADUs written to the device. This parameter is relevant only if the buf parameter points to a raw data buffer. In cases where it points to a device-defined structure it is redundant -- the size of the structure is known to the mini-driver and the application. At most, it can be used for error checking.
GIO_write returns IOM_COMPLETED upon successfully writing the requested number of MADUs from the device. If an error occurs, the device returns a negative value. For a list of error values, see ti/sybios/io/iom.h.
A call to GIO_write results in a call to the mdSubmit function of the associated mini-driver. The IOM_WRITE command is passed to the mdSubmit function. The mdSubmit call is typically a blocking call, so calling GIO_write can result in the thread blocking.
Instance Built-Ins

C synopsis target-domain
Int GIO_Object_count();
// The number of statically-created instance objects
 
GIO_Handle GIO_Object_get(GIO_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
GIO_Handle GIO_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
GIO_Handle GIO_Object_next(GIO_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle GIO_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *GIO_Handle_label(GIO_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String GIO_Handle_name(GIO_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/io/GIO.xdc
var GIO = xdc.useModule('ti.sysbios.io.GIO');
module-wide constants & types
    const GIO.INPUT// mode for input = 0x1;
    const GIO.OUTPUT// mode for output = 0x2;
 
    values of type GIO.Model// model for IO channel
 
        obj.fxn = Void(*)(Ptr,Int,Ptr,SizeT)  ...
        obj.arg = Ptr  ...
 
    var obj = new GIO.BasicView// ;
        obj.label = String  ...
        obj.freeCount = UInt  ...
        obj.doneCount = UInt  ...
        obj.submitCount = UInt  ...
        obj.model = String  ...
        obj.mode = String  ...
        obj.userSuppliedSync = Bool  ...
module-wide config parameters
        msg: "A_badModel: invalid use of API for current I/O model"
    };
        msg: "E_createFailed: mdCreateChan returned error %d"
    };
        msg: "E_notFound: %s name not found"
    };
 
module-wide functions
    GIO.addDeviceMeta// This API has been deprecated. Use DEV.create()(String name, String fxns, String initFxn, Int devid, String params) returns Void
per-instance config parameters
    var params = new GIO.Params// Instance config-params object;
        params.chanParams// channel parameters = Ptr null;
        params.model// I/O model = GIO.Model GIO.Model_STANDARD;
per-instance creation
    var inst = GIO.create// Create an instance-object(String name, UInt mode, params);
 
 
const GIO.INOUT

mode for input & output

Configuration settings
const GIO.INOUT = 0x3;
 
C SYNOPSIS
 
const GIO.INPUT

mode for input

Configuration settings
const GIO.INPUT = 0x1;
 
C SYNOPSIS
 
const GIO.OUTPUT

mode for output

Configuration settings
const GIO.OUTPUT = 0x2;
 
C SYNOPSIS
 
enum GIO.Model

model for IO channel

Configuration settings
values of type GIO.Model
    const GIO.Model_STANDARD;
    // used for read, write, submit
    const GIO.Model_ISSUERECLAIM;
    // used for issue, reclaim, prime
 
C SYNOPSIS
 
struct GIO.AppCallback

Application Callback Structure

Configuration settings
var obj = new GIO.AppCallback;
 
    obj.fxn = Void(*)(Ptr,Int,Ptr,SizeT)  ...
    obj.arg = Ptr  ...
 
DETAILS
Used with GIO_submit() for asynchronous callback.
C SYNOPSIS
 
metaonly struct GIO.BasicView
Configuration settings
var obj = new GIO.BasicView;
 
    obj.label = String  ...
    obj.freeCount = UInt  ...
    obj.doneCount = UInt  ...
    obj.submitCount = UInt  ...
    obj.model = String  ...
    obj.mode = String  ...
    obj.userSuppliedSync = Bool  ...
 
 
config GIO.A_badModel  // module-wide

Asserted in GIO_read(), GIO_write() if I/O model is not STANDARD or in GIO_issue(), GIO_reclaim(), or GIO_prime() if the I/O model is not ISSUERECLAIM

Configuration settings
GIO.A_badModel = Assert.Desc {
    msg: "A_badModel: invalid use of API for current I/O model"
};
 
C SYNOPSIS
 
config GIO.E_createFailed  // module-wide

Error raised when driver's mdCreateChan() call fails

Configuration settings
GIO.E_createFailed = Error.Desc {
    msg: "E_createFailed: mdCreateChan returned error %d"
};
 
C SYNOPSIS
 
config GIO.E_notFound  // module-wide

Error raised when name not found in DeviceTable

Configuration settings
GIO.E_notFound = Error.Desc {
    msg: "E_notFound: %s name not found"
};
 
C SYNOPSIS
 
config GIO.deviceTableSize  // module-wide

This configuration parameter has been deprecated. Use DEV.tableSize

Configuration settings
GIO.deviceTableSize = Int 8;
 
C SYNOPSIS
 
metaonly config GIO.common$  // module-wide

Common module configuration parameters

Configuration settings
GIO.common$ = Types.Common$ undefined;
 
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 GIO.rovViewInfo  // module-wide
Configuration settings
GIO.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly GIO.addDeviceMeta()  // module-wide

This API has been deprecated. Use DEV.create()

Configuration settings
GIO.addDeviceMeta(String name, String fxns, String initFxn, Int devid, String params) returns Void
 
Instance Config Parameters

Configuration settings
var params = new GIO.Params;
// Instance config-params object
    params.chanParams = Ptr null;
    // channel parameters
    params.model = GIO.Model GIO.Model_STANDARD;
    // I/O model
    params.numPackets = Int 2;
    // Number of packets to use for asynchronous I/O
    params.packets = Ptr null;
    // The address of the buffer used for IOM packets
    params.sync = ISync.Handle null;
    // ISync handle used to signal IO completion
    params.timeout = UInt ~(0);
    // For blocking calls. Default is BIOS_WAIT_FOREVER
 
config GIO.Params.chanParams  // instance

channel parameters

Configuration settings
var params = new GIO.Params;
  ...
params.chanParams = Ptr null;
 
DETAILS
The chanParams parameter is a pointer that may be used to pass device or domain-specific arguments to the mini-driver. The contents at the specified address are interpreted by the mini-driver in a device-specific manner.
C SYNOPSIS
 
config GIO.Params.model  // instance

I/O model

Configuration settings
var params = new GIO.Params;
  ...
params.model = GIO.Model GIO.Model_STANDARD;
 
DETAILS
Set the model to STANDARD to use read(), write() and submit() APIs. Set the model to ISSUERECLAIM to use issue(), reclaim(), and prime() APIs.
The default for this parameter is STANDARD.
C SYNOPSIS
 
config GIO.Params.numPackets  // instance

Number of packets to use for asynchronous I/O

Configuration settings
var params = new GIO.Params;
  ...
params.numPackets = Int 2;
 
C SYNOPSIS
 
config GIO.Params.packets  // instance

The address of the buffer used for IOM packets

Configuration settings
var params = new GIO.Params;
  ...
params.packets = Ptr null;
 
DETAILS
If set to 'null', the packets will be allocated from the heap during runtime, otherwise the user may set this to a buffer of their creation to be used for the IOM packets.
The packets will be split into ti.sysbios.io.GIO.numPackets each the size of IOM_Packet.
Please note that if the packets is user supplied, then it is the user's responsibility to ensure that it is aligned properly and is also large enough to contain ti.sysbios.io.GIO.numPackets number of IOM_Packet packets. The size of packets buffer, if provided, should be
      sizeof(IOM_Packet) * numPackets
Example:
  #define NUMPACKETS  2
  IOM_Packet inPackets[NUMPACKETS];

  GIO_Params params;

  GIO_Params_init(&params);
  params.numPackets = NUMPACKETS;
  params.packets = inPackets;
C SYNOPSIS
 
config GIO.Params.sync  // instance

ISync handle used to signal IO completion

Configuration settings
var params = new GIO.Params;
  ...
params.sync = ISync.Handle null;
 
C SYNOPSIS
 
config GIO.Params.timeout  // instance

For blocking calls. Default is BIOS_WAIT_FOREVER

Configuration settings
var params = new GIO.Params;
  ...
params.timeout = UInt ~(0);
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new GIO.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = GIO.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
An application calls GIO_create to create a GIO_Obj object and open a communication channel. This function initializes the I/O channel and opens the lower-level device driver channel. The GIO_create call also creates the synchronization objects it uses and stores them in the GIO_Obj object.
The name argument is the name specified for the device when it was created in the configuration or at runtime.
The mode argument specifies the mode in which the device is to be opened. This may be IOM_INPUT, IOM_OUTPUT, or IOM_INOUT.
If the status returned by the device is non-NULL, a status value is placed at the address specified by the status parameter.
The GIO_create call allocates a list of IOM_Packet items as specified by the numPackets member of the params structure and stores them in the GIO_Obj object it creates.
generated on Fri, 10 Jun 2016 23:29:38 GMT