Main Page   Modules   Alphabetical List   Data Structures   File List   Data Fields   Globals  

IXP425 ATM Driver Access (IxAtmdAcc) API

The public API for the IXP425 Atm Driver Data component. More...

Defines

#define IX_ATMDACC_WARNING
 Warning return code.

#define IX_ATMDACC_BUSY
 Busy return code.

#define IX_ATMDACC_RESOURCES_STILL_ALLOCATED
 Disconnect return code.

#define IX_ATMDACC_DEFAULT_REPLENISH_COUNT
 Default resources usage for RxVcFree replenish mechanism.

#define IX_ATMDACC_OAM_TX_VPI
 The reserved value used for the dedicated OAM Tx connection. This "well known" value is used by atmdAcc and its clients to dsicriminate the OAM channel, and should be chosen so that it does not coencide with the VPI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VPI will fail.

#define IX_ATMDACC_OAM_TX_VCI
 The reserved value used for the dedicated OAM Tx connection. This "well known" value is used by atmdAcc and its clients to dsicriminate the OAM channel, and should be chosen so that it does not coencide with the VCI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VCI will fail.

#define IX_ATMDACC_OAM_RX_PORT
 The reserved dummy PORT used for all dedicated OAM Rx connections. Note that this is not a real port but must have a value that lies within the valid range of port values.

#define IX_ATMDACC_OAM_RX_VPI
 The reserved value value used for the dedicated OAM Rx connection. This value should be chosen so that it does not coencide with the VPI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VPI will fail.

#define IX_ATMDACC_OAM_RX_VCI
 The reserved value value used for the dedicated OAM Rx connection. This value should be chosen so that it does not coencide with the VCI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VCI will fail.


Typedefs

typedef unsigned int IxAtmdAccUserId
 User-supplied Id.

typedef void(* IxAtmdAccRxVcRxCallback )(IxAtmLogicalPort port, IxAtmdAccUserId userId, IxAtmdAccPduStatus status, IxAtmdAccClpStatus clp, IX_MBUF *mbufPtr)
 Rx callback prototype.

typedef void(* IxAtmdAccRxVcFreeLowCallback )(IxAtmdAccUserId userId)
 Callback prototype for free buffer level is low.

typedef void(* IxAtmdAccTxVcBufferReturnCallback )(IxAtmdAccUserId userId, IX_MBUF *mbufPtr)
 Buffer callback prototype.


Enumerations

enum  IxAtmdAccPduStatus {
  IX_ATMDACC_AAL0_VALID,
  IX_ATMDACC_OAM_VALID,
  IX_ATMDACC_AAL2_VALID,
  IX_ATMDACC_AAL5_VALID,
  IX_ATMDACC_AAL5_PARTIAL,
  IX_ATMDACC_AAL5_CRC_ERROR,
  IX_ATMDACC_MBUF_RETURN
}
 IxAtmdAcc Pdu status :. More...

enum  IxAtmdAccAalType {
  IX_ATMDACC_AAL5,
  IX_ATMDACC_AAL2,
  IX_ATMDACC_AAL0_48,
  IX_ATMDACC_AAL0_52,
  IX_ATMDACC_OAM,
  IX_ATMDACC_MAX_SERVICE_TYPE
}
 IxAtmdAcc AAL Service Type :. More...

enum  IxAtmdAccClpStatus {
  IX_ATMDACC_CLP_NOT_SET,
  IX_ATMDACC_CLP_SET
}
 IxAtmdAcc CLP indication. More...


Functions

PUBLIC IX_STATUS ixAtmdAccInit (void)
 Initialise the IxAtmdAcc Component.

PUBLIC void ixAtmdAccShow (void)
 Show IxAtmdAcc configuration on a per port basis.

PUBLIC void ixAtmdAccStatsShow (void)
 Show all IxAtmdAcc stats.

PUBLIC void ixAtmdAccStatsReset (void)
 Reset all IxAtmdAcc stats.

PUBLIC IX_STATUS ixAtmdAccRxVcConnect (IxAtmLogicalPort port, unsigned int vpi, unsigned int vci, IxAtmdAccAalType aalServiceType, IxAtmRxQueueId rxQueueId, IxAtmdAccUserId userCallbackId, IxAtmdAccRxVcRxCallback rxCallback, unsigned int minimumReplenishCount, IxAtmConnId *connIdPtr, IxAtmNpeRxVcId *npeVcIdPtr)
 Connect to a Aal Pdu receive service for a particular port/vpi/vci, and service type.

PUBLIC IX_STATUS ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId, IX_MBUF *mbufPtr)
 Provide free mbufs for data reception on a connection.

PUBLIC IX_STATUS ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId, unsigned int numberOfMbufs, IxAtmdAccRxVcFreeLowCallback callback)
 Configure the RX Free threshold value and register a callback to handle threshold notifications.

PUBLIC IX_STATUS ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId, unsigned int *numberOfMbufsPtr)
 Get the number of rx mbufs the system can accept to replenish the the rx reception mechanism on a particular channel.

PUBLIC IX_STATUS ixAtmdAccRxVcEnable (IxAtmConnId connId)
 Start the RX service on a VC.

PUBLIC IX_STATUS ixAtmdAccRxVcDisable (IxAtmConnId connId)
 Stop the RX service on a VC.

PUBLIC IX_STATUS ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId)
 Disconnect a VC from the RX service.

PUBLIC IX_STATUS ixAtmdAccTxVcConnect (IxAtmLogicalPort port, unsigned int vpi, unsigned int vci, IxAtmdAccAalType aalServiceType, IxAtmdAccUserId userId, IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback, IxAtmConnId *connIdPtr)
 Connect to a Aal Pdu transmit service for a particular port/vpi/vci and service type.

PUBLIC IX_STATUS ixAtmdAccTxVcPduSubmit (IxAtmConnId connId, IX_MBUF *mbufPtr, IxAtmdAccClpStatus clp, unsigned int numberOfCells)
 Submit a Pdu for transmission on connection.

PUBLIC IX_STATUS ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId)
 Disconnect from a Aal Pdu transmit service for a particular port/vpi/vci.


Detailed Description

The public API for the IXP425 Atm Driver Data component.

IxAtmdAcc is the low level interface by which AAL0/AAL5 and OAM data gets transmitted to,and received from the Utopia bus.

For AAL0/AAL5 services transmit and receive connections may be established independantly for unique combinations of port,VPI,and VCI.

Two AAL0 services supporting 48 or 52 byte cell data are provided. Submitted AAL0 PDUs must be a multiple of the cell data size (48/52). AAL0_52 is a raw cell service the client must format the PDU with an ATM cell header (excluding HEC) at the start of each cell, note that AtmdAcc does not validate the cell headers in a submitted PDU.

OAM cells cannot be received over the AAL0 service but instead are received over a dedicated OAM service.

For the OAM service an "OAM Tx channel" may be enabled for a port by establishing a single dedicated OAM Tx connection on that port. A single "OAM Rx channel" for all ports may be enabled by establishing a dedicated OAM Rx connection.

The OAM service allows buffers containing 52 byte OAM F4/F5 cells to be transmitted and received over the dedicated OAM channels. HEC is appended/removed, and CRC-10 performed by the NPE. The OAM service offered by AtmdAcc is a raw cell transport service. It is assumed that ITU I.610 procedures that make use of this service are implemented above AtmdAcc.

Note that the dedicated OAM connections are established on reserved VPI,VCI, and (in the case of Rx) port values defined below. These values are used purely to descriminate the dedicated OAM channels and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be realised for particluar VPI/VCIs by manipulating the VPI,VCI fields of the ATM cell headers of cells in the buffers passed to AtmdAcc. Note that AtmdAcc does not validate the cell headers in a submitted OAM PDU.

This part is related to the User datapath processing


Define Documentation

#define IX_ATMDACC_BUSY
 

Busy return code.

This constant is used to tell IxAtmDAcc user that the request is correct, but cannot be processed because the IxAtmAcc resources are already used. The user has to retry its request later

Definition at line 148 of file IxAtmdAcc.h.

#define IX_ATMDACC_DEFAULT_REPLENISH_COUNT
 

Default resources usage for RxVcFree replenish mechanism.

This constant is used to tell IxAtmDAcc to allocate and use the minimum of resources for rx free replenish.

See also:
ixAtmdAccRxVcConnect

Definition at line 179 of file IxAtmdAcc.h.

#define IX_ATMDACC_OAM_RX_PORT
 

The reserved dummy PORT used for all dedicated OAM Rx connections. Note that this is not a real port but must have a value that lies within the valid range of port values.

Definition at line 220 of file IxAtmdAcc.h.

#define IX_ATMDACC_OAM_RX_VCI
 

The reserved value value used for the dedicated OAM Rx connection. This value should be chosen so that it does not coencide with the VCI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VCI will fail.

Definition at line 244 of file IxAtmdAcc.h.

#define IX_ATMDACC_OAM_RX_VPI
 

The reserved value value used for the dedicated OAM Rx connection. This value should be chosen so that it does not coencide with the VPI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VPI will fail.

Definition at line 232 of file IxAtmdAcc.h.

#define IX_ATMDACC_OAM_TX_VCI
 

The reserved value used for the dedicated OAM Tx connection. This "well known" value is used by atmdAcc and its clients to dsicriminate the OAM channel, and should be chosen so that it does not coencide with the VCI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VCI will fail.

Definition at line 208 of file IxAtmdAcc.h.

#define IX_ATMDACC_OAM_TX_VPI
 

The reserved value used for the dedicated OAM Tx connection. This "well known" value is used by atmdAcc and its clients to dsicriminate the OAM channel, and should be chosen so that it does not coencide with the VPI value used in an AAL0/AAL5 connection. Any attempt to connect a service type other than OAM on this VPI will fail.

Definition at line 195 of file IxAtmdAcc.h.

#define IX_ATMDACC_RESOURCES_STILL_ALLOCATED
 

Disconnect return code.

This constant is used to tell IxAtmDAcc user that the disconnect functions are not complete because the resources used by the driver are not yet released. The user has to retry the disconnect call later.

Definition at line 164 of file IxAtmdAcc.h.

#define IX_ATMDACC_WARNING
 

Warning return code.

This constant is used to tell IxAtmDAcc user about a special case.

Definition at line 133 of file IxAtmdAcc.h.


Typedef Documentation

typedef void(* IxAtmdAccRxVcFreeLowCallback)(IxAtmdAccUserId userId)
 

Callback prototype for free buffer level is low.

IxAtmdAccRxVcFreeLowCallback is the prototype of the user function which get called on a per-VC basis, when more mbufs are needed to continue the ATM data reception. This function is likely to supply more available mbufs by one or many calls to the replenish function ixAtmdAccRxVcFreeReplenish()

This function is called when the number of available buffers for reception is going under the threshold level as defined in ixAtmdAccRxVcFreeLowCallbackRegister()

This function is called inside an Qmgr dispatch context. No system resource or interrupt-unsafe feature should be used inside this callback.

See also:
ixAtmdAccRxVcFreeLowCallbackRegister

IxAtmdAccRxVcFreeLowCallback

ixAtmdAccRxVcFreeReplenish

ixAtmdAccRxVcFreeEntriesQuery

ixAtmdAccRxVcConnect

Parameters:
userId (in) user Id provided in the call to ixAtmdAccRxVcConnect()
Returns:
None

Definition at line 413 of file IxAtmdAcc.h.

typedef void(* IxAtmdAccRxVcRxCallback)(IxAtmLogicalPort port, IxAtmdAccUserId userId, IxAtmdAccPduStatus status, IxAtmdAccClpStatus clp, IX_MBUF * mbufPtr)
 

Rx callback prototype.

IxAtmdAccRxVcRxCallback is the prototype of the Rx callback user function called once per PDU to pass a receive Pdu to a user on a partilcular connection. The callback is likely to push the mbufs to a protocol layer, and recycle the mbufs for a further use.

Note:
-This function is called ONLY in the context of the ixAtmdAccRxDispatch() function
See also:
ixAtmdAccRxDispatch

ixAtmdAccRxVcConnect

Parameters:
port (in) the port on which this PDU was received a logical PHY port [IX_UTOPIA_PORT_0 .. IX_UTOPIA_MAX_PORTS - 1]
userId (in) user Id provided in the call to ixAtmdAccRxVcConnect()
status (in) an indication about the PDU validity. In the case of AAL0 the only possibile value is AAL0_VALID, in this case the client may optionally determine that an rx timeout occured by checking if the mbuf is compleletly or only partially filled, the later case indicating a timeout. In the case of OAM the only possible value is OAM valid. The status is set to IX_ATMDACC_MBUF_RETURN when the mbuf is released during a disconnect process.
clp (in) clp indication for this PDU. For AAL5/AAL0_48 this information is set if the clp bit of any rx cell is set For AAL0-52/OAM the client may inspect the CLP in individual cell headers in the PDU, and this parameter is set to 0.
mbufPtr (in) depending on the servive type a pointer to an mbuf (AAL5/AAL0/OAM) or mbuf chain (AAL5 only), that comprises the complete PDU data.
This parameter is guaranteed not to be a null pointer.

Definition at line 375 of file IxAtmdAcc.h.

typedef void(* IxAtmdAccTxVcBufferReturnCallback)(IxAtmdAccUserId userId, IX_MBUF * mbufPtr)
 

Buffer callback prototype.

This function is called to relinguish ownership of a transmitted buffer chain to the user.

Note:
-In the case of a chained mbuf the AmtdAcc component can chain many user buffers together and pass ownership to the user in one function call.
Parameters:
userId (in) user If provided at registration of this callback.
mbufPtr (in) a pointer to mbufs or chain of mbufs and is guaranteed not to be a null pointer.

Definition at line 438 of file IxAtmdAcc.h.

IxAtmdAccUserId
 

User-supplied Id.

IxAtmdAccUserId is passed through callbacks and allows the IxAtmdAcc user to identify the source of a call back. The range of this user-owned Id is [0...2^32-1)].

The user provides this own Ids on a per-channel basis as a parameter in a call to ixAtmdAccRxVcConnect() or ixAtmdAccRxVcConnect()

See also:
ixAtmdAccRxVcConnect

ixAtmdAccTxVcConnect

Definition at line 327 of file IxAtmdAcc.h.


Enumeration Type Documentation

enum IxAtmdAccAalType
 

IxAtmdAcc AAL Service Type :.

IxAtmdAccAalType defines the type of traffic to run on this VC

Enumeration values:
IX_ATMDACC_AAL5  ITU-T AAL5.
IX_ATMDACC_AAL2  ITU-T AAL2 reserved for future use.
IX_ATMDACC_AAL0_48  AAL0 48 byte payloads (cell header is added by NPE).
IX_ATMDACC_AAL0_52  AAL0 52 byte cell data (HEC is added by NPE).
IX_ATMDACC_OAM  OAM cell transport service (HEC is added by NPE).
IX_ATMDACC_MAX_SERVICE_TYPE  not a service, used for parameter validation

Definition at line 282 of file IxAtmdAcc.h.

enum IxAtmdAccClpStatus
 

IxAtmdAcc CLP indication.

IxAtmdAccClpStatus defines the CLP status of the current PDU

Enumeration values:
IX_ATMDACC_CLP_NOT_SET  CLP indication is not set.
IX_ATMDACC_CLP_SET  CLP indication is set.

Definition at line 303 of file IxAtmdAcc.h.

enum IxAtmdAccPduStatus
 

IxAtmdAcc Pdu status :.

IxAtmdAccPduStatus is used during a RX operation to indicate the status of the received PDU

Enumeration values:
IX_ATMDACC_AAL0_VALID  aal0 pdu
IX_ATMDACC_OAM_VALID  OAM pdu.
IX_ATMDACC_AAL2_VALID  aal2 pdu reserved for future use
IX_ATMDACC_AAL5_VALID  aal5 pdu complete and trailer is valid
IX_ATMDACC_AAL5_PARTIAL  aal5 pdu not complete, trailer is missing
IX_ATMDACC_AAL5_CRC_ERROR  aal5 pdu not complete, crc error/length error
IX_ATMDACC_MBUF_RETURN  empty buffer returned to the user

Definition at line 259 of file IxAtmdAcc.h.


Function Documentation

ixAtmdAccInit void   ) 
 

Initialise the IxAtmdAcc Component.

This function initialise the IxAtmdAcc component. This function shall be called before any other function of the API. Its role is to initialise all internal resources of the IxAtmdAcc component.

The ixQmgr component needs to be initialized prior the use of ixAtmdAccInit()

Parameters:
none Failing to initilialize the IxAtmdAcc API before any use of it will result in a failed status. If the specified component is not present, a success status will still be returned, however, a warning indicating the NPE to download to is not present will be issued.
Returns:
  • IX_SUCCESS initialisation is complete (in case of component not being present, a warning is clearly indicated)

  • IX_FAIL unable to process this request either because this IxAtmdAcc is already initialised or some unspecified error has occrred.

ixAtmdAccRxVcConnect IxAtmLogicalPort  port,
unsigned int  vpi,
unsigned int  vci,
IxAtmdAccAalType  aalServiceType,
IxAtmRxQueueId  rxQueueId,
IxAtmdAccUserId  userCallbackId,
IxAtmdAccRxVcRxCallback  rxCallback,
unsigned int  minimumReplenishCount,
IxAtmConnId connIdPtr,
IxAtmNpeRxVcId npeVcIdPtr
 

Connect to a Aal Pdu receive service for a particular port/vpi/vci, and service type.

This function allows a user to connect to an Aal5/Aal0/OAM Pdu receive service for a particular port/vpi/vci. It registers the callback and allocates internal resources and a Connection Id to be used in further API calls related to this VCC.

The function will setup VC receive service on the specified rx queue.

This function is blocking and makes use internal locks, and hence should not be called from an interrupt context.

On return from ixAtmdAccRxVcConnect() with a failure status, the connection Id parameter is unspecified. Its value cannot be used. A connId is the reference by which IxAtmdAcc refers to a connected VC. This identifier is the result of a succesful call to a connect function. This identifier is invalid after a sucessful call to a disconnect function.

Calling this function for the same combination of Vpi, Vci and more than once without calling ixAtmdAccRxVcTryDisconnect() will result in a failure status.

If this function returns success the user should supply receive buffers by calling ixAtmdAccRxVcFreeReplenish() and then call ixAtmdAccRxVcEnable() to begin receiving pdus.

There is a choice of two receive Qs on which the VC pdus could be receive. The user must associate the VC with one of these. Essentially having two qs allows more flexible system configuration such as have high prioriy traffic on one q (e.g. voice) and low priority traffic on the other (e.g. data). The high priority Q could be serviced in preference to the low priority Q. One queue may be configured to be serviced as soon as there is traffic, the other queue may be configured to be serviced by a polling mechanism running at idle time.

Two AAL0 services supporting 48 or 52 byte cell data are provided. Received AAL0 PDUs will be be a multiple of the cell data size (48/52). AAL0_52 is a raw cell service and includes an ATM cell header (excluding HEC) at the start of each cell.

A single "OAM Rx channel" for all ports may be enabled by establishing a dedicated OAM Rx connection.

The OAM service allows buffers containing 52 byte OAM F4/F5 cells to be transmitted and received over the dedicated OAM channels. HEC is appended/removed, and CRC-10 performed by the NPE. The OAM service offered by AtmdAcc is a raw cell transport service. It is assumed that ITU I.610 procedures that make use of this service are implemented above AtmdAcc.

Note that the dedicated OAM connections are established on reserved VPI,VCI, and (in the case of Rx) port values. These values are used purely to descriminate the dedicated OAM channels and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be realised for particluar VPI/VCIs by manipulating the VPI,VCI fields of the ATM cell headers of cells in the buffers passed to AtmdAcc.

Calling this function prior to enable the port will fail.

See also:
ixAtmdAccRxDispatch

ixAtmdAccRxVcEnable

ixAtmdAccRxVcDisable

ixAtmdAccRxVcTryDisconnect

ixAtmdAccPortEnable

Parameters:
port (in) VC identification : logical PHY port [IX_UTOPIA_PORT_0 .. IX_UTOPIA_MAX_PORTS - 1]
vpi (in) VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
vci (in) VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
aalServiceType (in) type of service: AAL5, AAL0_48, AAL0_52, or OAM
rxQueueId (in) this identifieds which of two Qs the VC should use.when icoming traffic is processed
userCallbackId (in) user Id used later as a parameter to the supplied rxCallback.
rxCallback (in) function called when mbufs are received. This parameter cannot be a null pointer.
bufferFreeCallback (in) function to be called to return ownership of buffers to IxAtmdAcc user.
minimumReplenishCount (in) For AAL5/AAL0 the number of free mbufs to be used with this channel. Use a high number when the expected traffic rate on this channel is high, or when the user's mbufs are small, or when the RxVcFreeLow Notification has to be invoked less often. When this value is IX_ATMDACC_DEFAULT_REPLENISH_COUNT, the minimum of resources will be used. Depending on traffic rate, pdu size and mbuf size, rxfree queue size, polling/interrupt rate, this value may require to be replaced by a different value in the range 1-128 For OAM the rxFree queue size is fixed by atmdAcc and this parameter is ignored.
connIdPtr (out) pointer to a connection Id This parameter cannot be a null pointer.
npeVcIdPtr (out) pointer to an npe Vc Id This parameter cannot be a null pointer.
Returns:
  • IX_SUCCESS successful call to IxAtmdAccRxVcConnect

  • IX_ATMDACC_BUSY cannot process this request : no VC is available

  • IX_FAIL parameter error, VC already in use, attempt to connect AAL service on reserved OAM VPI/VCI, attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI, port is not initialised, or some other error occurs during processing.

ixAtmdAccRxVcDisable IxAtmConnId  connId  ) 
 

Stop the RX service on a VC.

This functions stops the traffic reception for a particular VC connection.

Once invoked, incoming Pdus are discarded by the hardware. Any Pdus pending will be freed to the user

Hence once this function returns no more receive callbacks will be called for that VC. However, buffer free callbacks will be invoked until such time as all buffers supplied by the user have been freed back to the user

Calling this function doe not invalidate the connId. ixAtmdAccRxVcEnable() can be invoked to enable Pdu reception again.

If the traffic is already stopped, this function returns IX_SUCCESS.

This function is not reentrant and should not be used inside an interrupt context.

See also:
ixAtmdAccRxVcConnect

ixAtmdAccRxVcEnable

ixAtmdAccRxVcDisable

Parameters:
connId (in) connection Id as resulted from a succesfull call to IxAtmdAccRxVcConnect()
Returns:

  • IX_ATMDACC_WARNING the channel is already disabled

  • IX_FAIL invalid parameters or some unspecified internal error occured

ixAtmdAccRxVcEnable IxAtmConnId  connId  ) 
 

Start the RX service on a VC.

This functions kicks-off the traffic reception for a particular VC. Once invoked, incoming PDUs will be made available by the hardware and are eventually directed to the IxAtmdAccRxVcRxCallback() callback registered for the connection.

If the traffic is already running, this function returns IX_SUCCESS. This function can be invoked many times.

IxAtmdAccRxVcFreeLowCallback event will occur only after ixAtmdAccRxVcEnable() function is invoked.

Before using this function, the ixAtmdAccRxVcFreeReplenish() function has to be used to replenish the RX Free queue. If not, incoming traffic may be discarded.and in the case of interrupt driven reception the IxAtmdAccRxVcFreeLowCallback() callback may be invoked as a side effect during a replenish action.

This function is not reentrant and should not be used inside an interrupt context.

For an VC connection this function can be called after a call to ixAtmdAccRxVcDisable() and should not be called after ixAtmdAccRxVcTryDisconnect()

See also:
ixAtmdAccRxVcDisable

ixAtmdAccRxVcConnect

ixAtmdAccRxVcFreeReplenish

Parameters:
connId (in)connection Id as resulted from a succesfull call to IxAtmdAccRxVcConnect()
Returns:
  • IX_SUCCESS successful call to ixAtmdAccRxVcEnable

  • IX_ATMDACC_WARNING the channel is already enabled

  • IX_FAIL invalid parameters or some unspecified internal error occured.

ixAtmdAccRxVcFreeEntriesQuery IxAtmConnId  connId,
unsigned int *  numberOfMbufsPtr
 

Get the number of rx mbufs the system can accept to replenish the the rx reception mechanism on a particular channel.

The ixAtmdAccRxVcFreeEntriesQuery function is used to retrieve the current number of available mbuf entries for reception, on a per-VC basis. This function can be used to know the number of mbufs which can be provided using ixAtmdAccRxVcFreeReplenish().

This function can be used from a timer context, or can be associated with a threshold event, or can be used inside an active polling mechanism which is under user control.

This function is reentrant and does not use system resources and can be invoked from an interrupt context.

Parameters:
connId (in) connection Id as resulted from a succesfull call to IxAtmdAccRxVcConnect()
numberOfMbufsPtr (out) Pointer to the number of available entries. . This parameter cannot be a null pointer.
Returns:
  • IX_SUCCESS the current number of mbufs not yet used for incoming traffic

  • IX_FAIL invalid parameter
See also:
ixAtmdAccRxVcFreeReplenish

ixAtmdAccRxVcFreeLowCallbackRegister IxAtmConnId  connId,
unsigned int  numberOfMbufs,
IxAtmdAccRxVcFreeLowCallback  callback
 

Configure the RX Free threshold value and register a callback to handle threshold notifications.

The function ixAtmdAccRxVcFreeLowCallbackRegister sets the threshold value for a particular RX VC. When the number of buffers reaches this threshold the callback is invoked.

This function should be called once per VC before RX traffic is enabled.This function will fail if the curent level of the free buffers is equal or less than the threshold value.

See also:
ixAtmdAccRxVcFreeLowCallbackRegister

IxAtmdAccRxVcFreeLowCallback

ixAtmdAccRxVcFreeReplenish

ixAtmdAccRxVcFreeEntriesQuery

ixAtmdAccRxVcConnect

Parameters:
connId (in) connection Id as resulted from a succesfull call to IxAtmdAccRxVcConnect()
numberOfMbufs (in) threshold number of buffers. This number has to be a power of 2, one of the values 0,1,2,4,8,16,32.... The maximum value cannot be more than half of the rxFree queue size (which can be retrieved using ixAtmdAccRxVcFreeEntriesQuery() before any use of the ixAtmdAccRxVcFreeReplenish() function)
callback (in) function telling the user that the number of free buffers has reduced to the threshold value.
Returns:
  • IX_SUCCESS Threshold set successfully.

  • IX_FAIL parameter error or the current number of free buffers is less than or equal to the threshold supplied or some unspecified error has occrred.
Note:
- the callback will be called when the threshold level will drop from exactly (numberOfMbufs + 1) to (numberOfMbufs).

ixAtmdAccRxVcFreeReplenish IxAtmConnId  connId,
IX_MBUF *  mbufPtr
 

Provide free mbufs for data reception on a connection.

This function provides mbufs for data reception by the hardware. This function needs to be called by the user on a regular basis to ensure no packet loss. Providing free buffers is a connection-based feature; each connection can have different requirements in terms of buffer size number of buffers, recycling rate. This function could be invoked from within the context of a IxAtmdAccRxVcFreeLowCallback() callback for a particular VC

Mbufs provided through this function call can be chained. They will be unchained internally. A call to this function with chained mbufs or multiple calls with unchained mbufs are equivalent, but calls with unchained mbufs are more efficients.

Mbufs provided to this interface need to be able to hold at least one full cell payload (48/52 bytes, depending on service type). Chained buffers with a size less than the size supported by the hardware will be returned through the rx callback provided during the connect step.

Failing to invoke this function prior to enabling the RX traffic can result in packet loss.

This function is not reentrant for the same connId.

This function does not use system resources and can be invoked from an interrupt context.

Note:
- Over replenish is detected, and extra mbufs are returned through the rx callback provided during the connect step.

- Mbuf provided to the replenish function should have a length greater or equal to 48/52 bytes according to service type.

- The memory cache of mMbuf payload should be invalidated prior to Mbuf submission. Flushing the Mbuf headers is handled by IxAtmdAcc.

- When a chained mbuf is provided, this function process the mbufs up to the hardware limit and invokes the user-supplied callback to release extra buffers.

See also:
ixAtmdAccRxVcFreeLowCallbackRegister

IxAtmdAccRxVcFreeLowCallback

ixAtmdAccRxVcConnect

Parameters:
connId (in) connection Id as returned from a succesfull call to IxAtmdAccRxVcConnect()
mbufPtr (in) pointer to a mbuf structure to be used for data reception. The mbuf pointed to by this parameter can be chained to an other mbuf.
Returns:

  • IX_ATMDACC_BUSY cannot process this request because the max number of outstanding free buffers has been reached or the internal resources have exhausted for this VC. The user is responsible for retrying this request later.

  • IX_FAIL cannot process this request because of parameter errors or some unspecified internal error has occurred.
Note:
- It is not always guaranteed the replenish step to be as fast as the hardware is consuming Rx Free mbufs. There is nothing in IxAtmdAcc to guarantee that replenish reaches the rxFree threshold level. If the threshold level is not reached, the next rxFree low notification for this channel will not be triggered. The preferred ways to replenish can be as follows (depending on applications and implementations) :
  • Replenish in a rxFree low notification until the function ixAtmdAccRxVcFreeReplenish() returns IX_ATMDACC_BUSY
  • Query the queue level using
See also:
ixAtmdAccRxVcFreeEntriesQuery, then , replenish using ixAtmdAccRxVcFreeReplenish(), then query the queue level again, and replenish if the threshold is still not reached.
  • Trigger replenish from an other event source and use rxFree starvation to throttle the Rx traffic.

ixAtmdAccRxVcTryDisconnect IxAtmConnId  connId  ) 
 

Disconnect a VC from the RX service.

This function deregisters the VC and guarantees that all resources associated with this VC are free. After its execution, the connection Id is not available.

This function will fail until such time as all resources allocated to the VC connection have been freed. The user is responsible to delay and call again this function many times until a success status is returned.

This function needs internal locks and should not be called from an interrupt context

Parameters:
connId (in) connection Id as resulted from a succesfull call to IxAtmdAccRxVcConnect()
Returns:
  • IX_SUCCESS successful call to ixAtmdAccRxVcDisable

  • IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources associated with the connection have been freed.

  • IX_FAIL cannot process this request because of a parameter error

ixAtmdAccShow void   ) 
 

Show IxAtmdAcc configuration on a per port basis.

Parameters:
none 
Returns:
none
Note:
- Display use printf() and are redirected to stdout

ixAtmdAccStatsReset void   ) 
 

Reset all IxAtmdAcc stats.

Parameters:
none 
Returns:
none

ixAtmdAccStatsShow void   ) 
 

Show all IxAtmdAcc stats.

Parameters:
none 
Returns:
none
Note:
- Stats display use printf() and are redirected to stdout

ixAtmdAccTxVcConnect IxAtmLogicalPort  port,
unsigned int  vpi,
unsigned int  vci,
IxAtmdAccAalType  aalServiceType,
IxAtmdAccUserId  userId,
IxAtmdAccTxVcBufferReturnCallback  bufferFreeCallback,
IxAtmConnId connIdPtr
 

Connect to a Aal Pdu transmit service for a particular port/vpi/vci and service type.

This function allows a user to connect to an Aal5/Aal0/OAM Pdu transmit service for a particular port/vpi/vci. It registers the callback and allocates internal resources and a Connection Id to be used in further API calls related to this VC.

The function will setup VC transmit service on the specified on the specified port. A connId is the reference by which IxAtmdAcc refers to a connected VC. This identifier is the result of a succesful call to a connect function. This identifier is invalid after a sucessful call to a disconnect function.

This function needs internal locks, and hence should not be called from an interrupt context.

On return from ixAtmdAccTxVcConnect() with a failure status, the connection Id parameter is unspecified. Its value cannot be used.

Calling this function for the same combination of port, Vpi, Vci and more than once without calling ixAtmdAccTxVcTryDisconnect() will result in a failure status.

Two AAL0 services supporting 48 or 52 byte cell data are provided. Submitted AAL0 PDUs must be a multiple of the cell data size (48/52). AAL0_52 is a raw cell service the client must format the PDU with an ATM cell header (excluding HEC) at the start of each cell, note that AtmdAcc does not validate the cell headers in a submitted PDU.

For the OAM service an "OAM Tx channel" may be enabled for a port by establishing a single dedicated OAM Tx connection on that port.

The OAM service allows buffers containing 52 byte OAM F4/F5 cells to be transmitted and received over the dedicated OAM channels. HEC is appended/removed, and CRC-10 performed by the NPE. The OAM service offered by AtmdAcc is a raw cell transport service. It is assumed that ITU I.610 procedures that make use of this service are implemented above AtmdAcc.

Note that the dedicated OAM connections are established on reserved VPI,VCI, and (in the case of Rx) port values. These values are used purely to descriminate the dedicated OAM channels and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be realised for particluar VPI/VCIs by manipulating the VPI,VCI fields of the ATM cell headers of cells in the buffers passed to AtmdAcc.

Calling this function before enabling the port will fail.

See also:
ixAtmdAccTxVcTryDisconnect

ixAtmdAccPortTxScheduledModeEnable

ixAtmdAccPortEnable

Parameters:
port (in) VC identification : logical PHY port [IX_UTOPIA_PORT_0 .. IX_UTOPIA_MAX_PORTS - 1]
vpi (in) VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
vci (in) VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
aalServiceType (in) type of service AAL5, AAL0_48, AAL0_52, or OAM
userId (in) user id to be used later during callbacks related to this channel
bufferFreeCallback (in) function called when mbufs transmission is complete. This parameter cannot be a null pointer.
connIdPtr (out) Pointer to a connection Id. This parameter cannot be a null pointer.
Returns:
  • IX_SUCCESS successful call to IxAtmdAccRxVcConnect().

  • IX_ATMDACC_BUSY cannot process this request because no VC is available

  • IX_FAIL parameter error, VC already in use, attempt to connect AAL service on reserved OAM VPI/VCI, attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI, port is not initialised, or some other error occurs during processing.
Note:
- Unscheduled mode is not supported in ixp425 1.0. Therefore, the function ixAtmdAccPortTxScheduledModeEnable() need to be called for this port before any establishing a Tx Connection

ixAtmdAccTxVcPduSubmit IxAtmConnId  connId,
IX_MBUF *  mbufPtr,
IxAtmdAccClpStatus  clp,
unsigned int  numberOfCells
 

Submit a Pdu for transmission on connection.

A data user calls this function to submit an mbufs containing a Pdu to be transmitted. The buffer supplied can be chained and the Pdu it contains must be complete.

The transmission behavior of this call depends on the operational mode of the port on which the connection is made.

In unscheduled mode the mbuf will be submitted to the hardware immediately if sufficent resource is available. Otherwise the function will return failure.

In scheduled mode the buffer is queued internally in IxAtmdAcc. The cell demand is made known to the traffic shaping entity. Cells from the buffers are MUXed onto the port some time later as dictated by the traffic shaping entity. The traffic shaping entity does this by sending transmit schedules to IxAtmdAcc via ixAtmdAccPortTxProcess() function call.

Note that the dedicated OAM channel is scheduled just like any other channel. This means that any OAM traffic relating to an active AAL0/AAL5 connection will be scheduled independantly of the AAL0/AAL5 traffic for that connection.

When transmission is complete, the TX Done mechanism will give the owmnership of these buffers back to the customer. The tx done mechanism must be in operation before transmission is attempted.

For AAL0/OAM submitted AAL0 PDUs must be a multiple of the cell data size (48/52). AAL0_52 and OAM are raw cell services, and the client must format the PDU with an ATM cell header (excluding HEC) at the start of each cell, note that AtmdAcc does not validate the cell headers in a submitted PDU.

See also:
IxAtmdAccTxVcBufferReturnCallback

ixAtmdAccTxDoneDispatch

Parameters:
connId (in) connection Id as resulted from a succesfull call to ixAtmdAccTxVcConnect()
mbufPtr (in) pointer to a chained structure of mbufs to transmit. This parameter cannot be a null pointer.
clp (in) clp indication for this PDU. All cells of this pdu will be sent with the clp bit set
numberOfCells (in) number of cells in the PDU.
Returns:

  • IX_ATMDACC_BUSY unable to process this request because internal resources are all used. The caller is responsible for retrying this request later.

  • IX_FAIL unable to process this request because of error in the parameters (wrong connId supplied, or wrong mbuf pointer supplied), the total length of all buffers in the chain should be a multiple of the cell size ( 48/52 depending on the service type ), or unspecified error during processing
Note:
- This function in not re-entrant for the same VC (e.g. : two thread cannot send PDUs for the same VC). But two threads can safely call this function with a different connection Id

- In unscheduled mode, this function is not re-entrant on a per port basis. The size of pdus is limited to 8Kb.

- 0-length mbufs should be removed from the chain before submission. The total length of the pdu (sdu + padding +trailer) has to be updated in the header of the first mbuf of a chain of mbufs.

- Aal5 trailer information (UUI, CPI, SDU length) has to be supplied before submission.

- The payload memory cache should be flushed, if needed, prior to transmission. Mbuf headers are flushed by IxAtmdAcc

- This function does not use system resources and can be used inside an interrupt context

ixAtmdAccTxVcTryDisconnect IxAtmConnId  connId  ) 
 

Disconnect from a Aal Pdu transmit service for a particular port/vpi/vci.

This function deregisters the VC and guarantees that all resources associated with this VC are free. After its execution, the connection Id is not available.

This function will fail until such time as all resources allocated to the VC connection have been freed. The user is responsible to delay and call again this function many times until a success status is returned.

After its execution, the connection Id is not available.

Parameters:
connId (in) connection Id as resulted from a succesfull call to ixAtmdAccTxVcConnect()
Returns:

  • IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources associated with the connection have been freed. This condition will disappear after Tx and TxDone is complete for this channel.

  • IX_FAIL unable to process this request because of errors in the parameters (wrong connId supplied)
Note:
- This function needs internal locks and should not be called from an interrupt context

- If the IX_ATMDACC_RESOURCES_STILL_ALLOCATED error does not clear after a while, this may be linked to a previous problem of cell overscheduling. Diabling the port and retry a disconnect will free the resources associated with this channel.

See also:
ixAtmdAccPortTxProcess

Automatically generated from sources. © Intel Corp. 2003