IxAtmdAcc.h 44 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170
  1. /**
  2. * @file IxAtmdAcc.h
  3. *
  4. * @date 07-Nov-2001
  5. *
  6. * @brief IxAtmdAcc Public API
  7. *
  8. * This file contains the public API of IxAtmdAcc, related to the
  9. * data functions of the component
  10. *
  11. *
  12. * @par
  13. * IXP400 SW Release version 2.0
  14. *
  15. * -- Copyright Notice --
  16. *
  17. * @par
  18. * Copyright 2001-2005, Intel Corporation.
  19. * All rights reserved.
  20. *
  21. * @par
  22. * SPDX-License-Identifier: BSD-3-Clause
  23. * @par
  24. * -- End of Copyright Notice --
  25. */
  26. /* ------------------------------------------------------
  27. Doxygen group definitions
  28. ------------------------------------------------------ */
  29. /**
  30. *
  31. * @defgroup IxAtmdAccAPI IXP400 ATM Driver Access (IxAtmdAcc) API
  32. *
  33. * @brief The public API for the IXP400 Atm Driver Data component
  34. *
  35. * IxAtmdAcc is the low level interface by which AAL0/AAL5 and
  36. * OAM data gets transmitted to,and received from the Utopia bus.
  37. *
  38. * For AAL0/AAL5 services transmit and receive connections may
  39. * be established independantly for unique combinations of
  40. * port,VPI,and VCI.
  41. *
  42. * Two AAL0 services supporting 48 or 52 byte cell data are provided.
  43. * Submitted AAL0 PDUs must be a multiple of the cell data size (48/52).
  44. * AAL0_52 is a raw cell service the client must format
  45. * the PDU with an ATM cell header (excluding HEC) at the start of
  46. * each cell, note that AtmdAcc does not validate the cell headers in
  47. * a submitted PDU.
  48. *
  49. * OAM cells cannot be received over the AAL0 service but instead
  50. * are received over a dedicated OAM service.
  51. *
  52. * For the OAM service an "OAM Tx channel" may be enabled for a port
  53. * by establishing a single dedicated OAM Tx connection on that port.
  54. * A single "OAM Rx channel" for all ports may be enabled by
  55. * establishing a dedicated OAM Rx connection.
  56. *
  57. * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
  58. * to be transmitted and received over the dedicated OAM channels.
  59. * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
  60. * service offered by AtmdAcc is a raw cell transport service.
  61. * It is assumed that ITU I.610 procedures that make use of this
  62. * service are implemented above AtmdAcc.
  63. *
  64. * Note that the dedicated OAM connections are established on
  65. * reserved VPI,VCI, and (in the case of Rx) port values defined below.
  66. * These values are used purely to descriminate the dedicated OAM channels
  67. * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
  68. * realised for particluar VPI/VCIs by manipulating the VPI,VCI
  69. * fields of the ATM cell headers of cells in the buffers passed
  70. * to AtmdAcc. Note that AtmdAcc does not validate the cell headers
  71. * in a submitted OAM PDU.
  72. *
  73. *
  74. *
  75. * This part is related to the User datapath processing
  76. *
  77. * @{
  78. */
  79. #ifndef IXATMDACC_H
  80. #define IXATMDACC_H
  81. #include "IxAtmTypes.h"
  82. /* ------------------------------------------------------
  83. AtmdAcc Data Types definition
  84. ------------------------------------------------------ */
  85. /**
  86. *
  87. * @ingroup IxAtmdAccAPI
  88. *
  89. * @def IX_ATMDACC_WARNING
  90. *
  91. * @brief Warning return code
  92. *
  93. * This constant is used to tell IxAtmDAcc user about a special case.
  94. *
  95. */
  96. #define IX_ATMDACC_WARNING 2
  97. /**
  98. *
  99. * @ingroup IxAtmdAccAPI
  100. *
  101. * @def IX_ATMDACC_BUSY
  102. *
  103. * @brief Busy return code
  104. *
  105. * This constant is used to tell IxAtmDAcc user that the request
  106. * is correct, but cannot be processed because the IxAtmAcc resources
  107. * are already used. The user has to retry its request later
  108. *
  109. */
  110. #define IX_ATMDACC_BUSY 3
  111. /**
  112. *
  113. * @ingroup IxAtmdAccAPI
  114. *
  115. * @def IX_ATMDACC_RESOURCES_STILL_ALLOCATED
  116. *
  117. * @brief Disconnect return code
  118. *
  119. * This constant is used to tell IxAtmDAcc user that the disconnect
  120. * functions are not complete because the resources used by the driver
  121. * are not yet released. The user has to retry the disconnect call
  122. * later.
  123. *
  124. */
  125. #define IX_ATMDACC_RESOURCES_STILL_ALLOCATED 4
  126. /**
  127. *
  128. * @ingroup IxAtmdAccAPI
  129. *
  130. * @def IX_ATMDACC_DEFAULT_REPLENISH_COUNT
  131. *
  132. * @brief Default resources usage for RxVcFree replenish mechanism
  133. *
  134. * This constant is used to tell IxAtmDAcc to allocate and use
  135. * the minimum of resources for rx free replenish.
  136. *
  137. * @sa ixAtmdAccRxVcConnect
  138. */
  139. #define IX_ATMDACC_DEFAULT_REPLENISH_COUNT 0
  140. /**
  141. * @ingroup IxAtmdAccAPI
  142. *
  143. * @def IX_ATMDACC_OAM_TX_VPI
  144. *
  145. * @brief The reserved value used for the dedicated OAM
  146. * Tx connection. This "well known" value is used by atmdAcc and
  147. * its clients to dsicriminate the OAM channel, and should be chosen so
  148. * that it does not coencide with the VPI value used in an AAL0/AAL5 connection.
  149. * Any attempt to connect a service type other than OAM on this VPI will fail.
  150. *
  151. *
  152. */
  153. #define IX_ATMDACC_OAM_TX_VPI 0
  154. /**
  155. * @ingroup IxAtmdAccAPI
  156. *
  157. * @def IX_ATMDACC_OAM_TX_VCI
  158. *
  159. * @brief The reserved value used for the dedicated OAM
  160. * Tx connection. This "well known" value is used by atmdAcc and
  161. * its clients to dsicriminate the OAM channel, and should be chosen so
  162. * that it does not coencide with the VCI value used in an AAL0/AAL5 connection.
  163. * Any attempt to connect a service type other than OAM on this VCI will fail.
  164. */
  165. #define IX_ATMDACC_OAM_TX_VCI 0
  166. /**
  167. * @ingroup IxAtmdAccAPI
  168. *
  169. * @def IX_ATMDACC_OAM_RX_PORT
  170. *
  171. * @brief The reserved dummy PORT used for all dedicated OAM
  172. * Rx connections. Note that this is not a real port but must
  173. * have a value that lies within the valid range of port values.
  174. */
  175. #define IX_ATMDACC_OAM_RX_PORT IX_UTOPIA_PORT_0
  176. /**
  177. * @ingroup IxAtmdAccAPI
  178. *
  179. * @def IX_ATMDACC_OAM_RX_VPI
  180. *
  181. * @brief The reserved value value used for the dedicated OAM
  182. * Rx connection. This value should be chosen so that it does not
  183. * coencide with the VPI value used in an AAL0/AAL5 connection.
  184. * Any attempt to connect a service type other than OAM on this VPI will fail.
  185. */
  186. #define IX_ATMDACC_OAM_RX_VPI 0
  187. /**
  188. * @ingroup IxAtmdAccAPI
  189. *
  190. * @def IX_ATMDACC_OAM_RX_VCI
  191. *
  192. * @brief The reserved value value used for the dedicated OAM
  193. * Rx connection. This value should be chosen so that it does not
  194. * coencide with the VCI value used in an AAL0/AAL5 connection.
  195. * Any attempt to connect a service type other than OAM on this VCI will fail.
  196. */
  197. #define IX_ATMDACC_OAM_RX_VCI 0
  198. /**
  199. * @enum IxAtmdAccPduStatus
  200. *
  201. * @ingroup IxAtmdAccAPI
  202. *
  203. * @brief IxAtmdAcc Pdu status :
  204. *
  205. * IxAtmdAccPduStatus is used during a RX operation to indicate
  206. * the status of the received PDU
  207. *
  208. */
  209. typedef enum
  210. {
  211. IX_ATMDACC_AAL0_VALID = 0, /**< aal0 pdu */
  212. IX_ATMDACC_OAM_VALID, /**< OAM pdu */
  213. IX_ATMDACC_AAL2_VALID, /**< aal2 pdu @b reserved for future use */
  214. IX_ATMDACC_AAL5_VALID, /**< aal5 pdu complete and trailer is valid */
  215. IX_ATMDACC_AAL5_PARTIAL, /**< aal5 pdu not complete, trailer is missing */
  216. IX_ATMDACC_AAL5_CRC_ERROR, /**< aal5 pdu not complete, crc error/length error */
  217. IX_ATMDACC_MBUF_RETURN /**< empty buffer returned to the user */
  218. } IxAtmdAccPduStatus;
  219. /**
  220. *
  221. * @enum IxAtmdAccAalType
  222. *
  223. * @ingroup IxAtmdAccAPI
  224. *
  225. * @brief IxAtmdAcc AAL Service Type :
  226. *
  227. * IxAtmdAccAalType defines the type of traffic to run on this VC
  228. *
  229. */
  230. typedef enum
  231. {
  232. IX_ATMDACC_AAL5, /**< ITU-T AAL5 */
  233. IX_ATMDACC_AAL2, /**< ITU-T AAL2 @b reserved for future use */
  234. IX_ATMDACC_AAL0_48, /**< AAL0 48 byte payloads (cell header is added by NPE)*/
  235. IX_ATMDACC_AAL0_52, /**< AAL0 52 byte cell data (HEC is added by NPE) */
  236. IX_ATMDACC_OAM, /**< OAM cell transport service (HEC is added by NPE)*/
  237. IX_ATMDACC_MAX_SERVICE_TYPE /**< not a service, used for parameter validation */
  238. } IxAtmdAccAalType;
  239. /**
  240. *
  241. * @enum IxAtmdAccClpStatus
  242. *
  243. * @ingroup IxAtmdAccAPI
  244. *
  245. * @brief IxAtmdAcc CLP indication
  246. *
  247. * IxAtmdAccClpStatus defines the CLP status of the current PDU
  248. *
  249. */
  250. typedef enum
  251. {
  252. IX_ATMDACC_CLP_NOT_SET = 0, /**< CLP indication is not set */
  253. IX_ATMDACC_CLP_SET = 1 /**< CLP indication is set */
  254. } IxAtmdAccClpStatus;
  255. /**
  256. * @typedef IxAtmdAccUserId
  257. *
  258. * @ingroup IxAtmdAccAPI
  259. *
  260. * @brief User-supplied Id
  261. *
  262. * IxAtmdAccUserId is passed through callbacks and allows the
  263. * IxAtmdAcc user to identify the source of a call back. The range of
  264. * this user-owned Id is [0...2^32-1)].
  265. *
  266. * The user provides this own Ids on a per-channel basis as a parameter
  267. * in a call to @a ixAtmdAccRxVcConnect() or @a ixAtmdAccRxVcConnect()
  268. *
  269. * @sa ixAtmdAccRxVcConnect
  270. * @sa ixAtmdAccTxVcConnect
  271. *
  272. */
  273. typedef unsigned int IxAtmdAccUserId;
  274. /* ------------------------------------------------------
  275. Part of the IxAtmdAcc interface related to RX traffic
  276. ------------------------------------------------------ */
  277. /**
  278. *
  279. * @ingroup IxAtmdAccAPI
  280. *
  281. * @brief Rx callback prototype
  282. *
  283. * IxAtmdAccRxVcRxCallback is the prototype of the Rx callback user
  284. * function called once per PDU to pass a receive Pdu to a user on a
  285. * partilcular connection. The callback is likely to push the mbufs
  286. * to a protocol layer, and recycle the mbufs for a further use.
  287. *
  288. * @note -This function is called ONLY in the context of
  289. * the @a ixAtmdAccRxDispatch() function
  290. *
  291. * @sa ixAtmdAccRxDispatch
  292. * @sa ixAtmdAccRxVcConnect
  293. *
  294. * @param port @ref IxAtmLogicalPort [in] - the port on which this PDU was received
  295. * a logical PHY port [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
  296. * @param userId @ref IxAtmdAccUserId [in] - user Id provided in the call
  297. * to @a ixAtmdAccRxVcConnect()
  298. * @param status @ref IxAtmdAccPduStatus [in] - an indication about the PDU validity.
  299. * In the case of AAL0 the only possibile value is
  300. * AAL0_VALID, in this case the client may optionally determine
  301. * that an rx timeout occured by checking if the mbuf is
  302. * compleletly or only partially filled, the later case
  303. * indicating a timeout.
  304. * In the case of OAM the only possible value is OAM valid.
  305. * The status is set to @a IX_ATMDACC_MBUF_RETURN when
  306. * the mbuf is released during a disconnect process.
  307. * @param clp @ref IxAtmdAccClpStatus [in] - clp indication for this PDU.
  308. * For AAL5/AAL0_48 this information
  309. * is set if the clp bit of any rx cell is set
  310. * For AAL0-52/OAM the client may inspect the CLP in individual
  311. * cell headers in the PDU, and this parameter is set to 0.
  312. * @param *mbufPtr @ref IX_OSAL_MBUF [in] - depending on the servive type a pointer to
  313. * an mbuf (AAL5/AAL0/OAM) or mbuf chain (AAL5 only),
  314. * that comprises the complete PDU data.
  315. *
  316. * This parameter is guaranteed not to be a null pointer.
  317. *
  318. */
  319. typedef void (*IxAtmdAccRxVcRxCallback) (IxAtmLogicalPort port,
  320. IxAtmdAccUserId userId,
  321. IxAtmdAccPduStatus status,
  322. IxAtmdAccClpStatus clp,
  323. IX_OSAL_MBUF * mbufPtr);
  324. /**
  325. *
  326. * @ingroup IxAtmdAccAPI
  327. *
  328. * @brief Callback prototype for free buffer level is low.
  329. *
  330. * IxAtmdAccRxVcFreeLowCallback is the prototype of the user function
  331. * which get called on a per-VC basis, when more mbufs are needed to
  332. * continue the ATM data reception. This function is likely to supply
  333. * more available mbufs by one or many calls to the replenish function
  334. * @a ixAtmdAccRxVcFreeReplenish()
  335. *
  336. * This function is called when the number of available buffers for
  337. * reception is going under the threshold level as defined
  338. * in @a ixAtmdAccRxVcFreeLowCallbackRegister()
  339. *
  340. * This function is called inside an Qmgr dispatch context. No system
  341. * resource or interrupt-unsafe feature should be used inside this
  342. * callback.
  343. *
  344. * @sa ixAtmdAccRxVcFreeLowCallbackRegister
  345. * @sa IxAtmdAccRxVcFreeLowCallback
  346. * @sa ixAtmdAccRxVcFreeReplenish
  347. * @sa ixAtmdAccRxVcFreeEntriesQuery
  348. * @sa ixAtmdAccRxVcConnect
  349. *
  350. * @param userId @ref IxAtmdAccUserId [in] - user Id provided in the call
  351. * to @a ixAtmdAccRxVcConnect()
  352. *
  353. * @return None
  354. *
  355. */
  356. typedef void (*IxAtmdAccRxVcFreeLowCallback) (IxAtmdAccUserId userId);
  357. /* ------------------------------------------------------
  358. Part of the IxAtmdAcc interface related to TX traffic
  359. ------------------------------------------------------ */
  360. /**
  361. *
  362. * @ingroup IxAtmdAccAPI
  363. *
  364. * @brief Buffer callback prototype.
  365. *
  366. * This function is called to relinguish ownership of a transmitted
  367. * buffer chain to the user.
  368. *
  369. * @note -In the case of a chained mbuf the AmtdAcc component can
  370. * chain many user buffers together and pass ownership to the user in
  371. * one function call.
  372. *
  373. * @param userId @ref IxAtmdAccUserId [in] - user If provided at registration of this
  374. * callback.
  375. * @param mbufPtr @ref IX_OSAL_MBUF [in] - a pointer to mbufs or chain of mbufs and is
  376. * guaranteed not to be a null pointer.
  377. *
  378. */
  379. typedef void (*IxAtmdAccTxVcBufferReturnCallback) (IxAtmdAccUserId userId,
  380. IX_OSAL_MBUF * mbufPtr);
  381. /* ------------------------------------------------------
  382. Part of the IxAtmdAcc interface related to Initialisation
  383. ------------------------------------------------------ */
  384. /**
  385. *
  386. * @ingroup IxAtmdAccAPI
  387. *
  388. * @fn ixAtmdAccInit (void)
  389. *
  390. * @brief Initialise the IxAtmdAcc Component
  391. *
  392. * This function initialise the IxAtmdAcc component. This function shall
  393. * be called before any other function of the API. Its role is to
  394. * initialise all internal resources of the IxAtmdAcc component.
  395. *
  396. * The ixQmgr component needs to be initialized prior the use of
  397. * @a ixAtmdAccInit()
  398. *
  399. * @param none
  400. *
  401. * Failing to initilialize the IxAtmdAcc API before any use of it will
  402. * result in a failed status.
  403. * If the specified component is not present, a success status will still be
  404. * returned, however, a warning indicating the NPE to download to is not
  405. * present will be issued.
  406. *
  407. * @return @li IX_SUCCESS initialisation is complete (in case of component not
  408. * being present, a warning is clearly indicated)
  409. * @return @li IX_FAIL unable to process this request either
  410. * because this IxAtmdAcc is already initialised
  411. * or some unspecified error has occrred.
  412. */
  413. PUBLIC IX_STATUS ixAtmdAccInit (void);
  414. /**
  415. *
  416. * @ingroup IxAtmdAccAPI
  417. *
  418. * @fn ixAtmdAccShow (void)
  419. *
  420. * @brief Show IxAtmdAcc configuration on a per port basis
  421. *
  422. * @param none
  423. *
  424. * @return none
  425. *
  426. * @note - Display use printf() and are redirected to stdout
  427. */
  428. PUBLIC void
  429. ixAtmdAccShow (void);
  430. /**
  431. *
  432. * @ingroup IxAtmdAccAPI
  433. *
  434. * @fn ixAtmdAccStatsShow (void)
  435. *
  436. * @brief Show all IxAtmdAcc stats
  437. *
  438. * @param none
  439. *
  440. * @return none
  441. *
  442. * @note - Stats display use printf() and are redirected to stdout
  443. */
  444. PUBLIC void
  445. ixAtmdAccStatsShow (void);
  446. /**
  447. *
  448. * @ingroup IxAtmdAccAPI
  449. *
  450. * @fn ixAtmdAccStatsReset (void)
  451. *
  452. * @brief Reset all IxAtmdAcc stats
  453. *
  454. * @param none
  455. *
  456. * @return none
  457. *
  458. */
  459. PUBLIC void
  460. ixAtmdAccStatsReset (void);
  461. /* ------------------------------------------------------
  462. Part of the IxAtmdAcc interface related to RX traffic
  463. ------------------------------------------------------ */
  464. /**
  465. *
  466. * @ingroup IxAtmdAccAPI
  467. *
  468. * @fn ixAtmdAccRxVcConnect (IxAtmLogicalPort port,
  469. unsigned int vpi,
  470. unsigned int vci,
  471. IxAtmdAccAalType aalServiceType,
  472. IxAtmRxQueueId rxQueueId,
  473. IxAtmdAccUserId userCallbackId,
  474. IxAtmdAccRxVcRxCallback rxCallback,
  475. unsigned int minimumReplenishCount,
  476. IxAtmConnId * connIdPtr,
  477. IxAtmNpeRxVcId * npeVcIdPtr )
  478. *
  479. * @brief Connect to a Aal Pdu receive service for a particular
  480. * port/vpi/vci, and service type.
  481. *
  482. * This function allows a user to connect to an Aal5/Aal0/OAM Pdu receive service
  483. * for a particular port/vpi/vci. It registers the callback and allocates
  484. * internal resources and a Connection Id to be used in further API calls
  485. * related to this VCC.
  486. *
  487. * The function will setup VC receive service on the specified rx queue.
  488. *
  489. * This function is blocking and makes use internal locks, and hence
  490. * should not be called from an interrupt context.
  491. *
  492. * On return from @a ixAtmdAccRxVcConnect() with a failure status, the
  493. * connection Id parameter is unspecified. Its value cannot be used.
  494. * A connId is the reference by which IxAtmdAcc refers to a
  495. * connected VC. This identifier is the result of a succesful call
  496. * to a connect function. This identifier is invalid after a
  497. * sucessful call to a disconnect function.
  498. *
  499. * Calling this function for the same combination of Vpi, Vci and more
  500. * than once without calling @a ixAtmdAccRxVcTryDisconnect() will result in a
  501. * failure status.
  502. *
  503. * If this function returns success the user should supply receive
  504. * buffers by calling @a ixAtmdAccRxVcFreeReplenish() and then call
  505. * @a ixAtmdAccRxVcEnable() to begin receiving pdus.
  506. *
  507. * There is a choice of two receive Qs on which the VC pdus could be
  508. * receive. The user must associate the VC with one of these. Essentially
  509. * having two qs allows more flexible system configuration such as have
  510. * high prioriy traffic on one q (e.g. voice) and low priority traffic on
  511. * the other (e.g. data). The high priority Q could be serviced in
  512. * preference to the low priority Q. One queue may be configured to be
  513. * serviced as soon as there is traffic, the other queue may be configured
  514. * to be serviced by a polling mechanism running at idle time.
  515. *
  516. * Two AAL0 services supporting 48 or 52 byte cell data are provided.
  517. * Received AAL0 PDUs will be be a multiple of the cell data size (48/52).
  518. * AAL0_52 is a raw cell service and includes an ATM cell header
  519. * (excluding HEC) at the start of each cell.
  520. *
  521. * A single "OAM Rx channel" for all ports may be enabled by
  522. * establishing a dedicated OAM Rx connection.
  523. *
  524. * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
  525. * to be transmitted and received over the dedicated OAM channels.
  526. * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
  527. * service offered by AtmdAcc is a raw cell transport service.
  528. * It is assumed that ITU I.610 procedures that make use of this
  529. * service are implemented above AtmdAcc.
  530. *
  531. * Note that the dedicated OAM connections are established on
  532. * reserved VPI,VCI, and (in the case of Rx) port values.
  533. * These values are used purely to descriminate the dedicated OAM channels
  534. * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
  535. * realised for particluar VPI/VCIs by manipulating the VPI,VCI
  536. * fields of the ATM cell headers of cells in the buffers passed
  537. * to AtmdAcc.
  538. *
  539. * Calling this function prior to enable the port will fail.
  540. *
  541. * @sa ixAtmdAccRxDispatch
  542. * @sa ixAtmdAccRxVcEnable
  543. * @sa ixAtmdAccRxVcDisable
  544. * @sa ixAtmdAccRxVcTryDisconnect
  545. * @sa ixAtmdAccPortEnable
  546. *
  547. * @param port @ref IxAtmLogicalPort [in] - VC identification : logical PHY port
  548. * [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
  549. * @param vpi unsigned int [in] - VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
  550. * @param vci unsigned int [in] - VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
  551. * @param aalServiceType @ref IxAtmdAccAalType [in] - type of service: AAL5, AAL0_48, AAL0_52, or OAM
  552. * @param rxQueueId @ref IxAtmRxQueueId [in] - this identifieds which of two Qs the VC
  553. * should use.when icoming traffic is processed
  554. * @param userCallbackId @ref IxAtmdAccUserId [in] - user Id used later as a parameter to
  555. * the supplied rxCallback.
  556. * @param rxCallback [in] @ref IxAtmdAccRxVxRxCallback - function called when mbufs are received.
  557. * This parameter cannot be a null pointer.
  558. * @param bufferFreeCallback [in] - function to be called to return
  559. * ownership of buffers to IxAtmdAcc user.
  560. * @param minimumReplenishCount unsigned int [in] - For AAL5/AAL0 the number of free mbufs
  561. * to be used with this channel. Use a high number when the expected traffic
  562. * rate on this channel is high, or when the user's mbufs are small, or when
  563. * the RxVcFreeLow Notification has to be invoked less often. When this
  564. * value is IX_ATMDACC_DEFAULT_REPLENISH_COUNT, the minimum of
  565. * resources will be used. Depending on traffic rate, pdu
  566. * size and mbuf size, rxfree queue size, polling/interrupt rate, this value may
  567. * require to be replaced by a different value in the range 1-128
  568. * For OAM the rxFree queue size is fixed by atmdAcc and this parameter is ignored.
  569. * @param connIdPtr @ref IxAtmConnId [out] - pointer to a connection Id
  570. * This parameter cannot be a null pointer.
  571. * @param npeVcIdPtr @ref IxAtmNpeRxVcId [out] - pointer to an npe Vc Id
  572. * This parameter cannot be a null pointer.
  573. *
  574. * @return @li IX_SUCCESS successful call to IxAtmdAccRxVcConnect
  575. * @return @li IX_ATMDACC_BUSY cannot process this request :
  576. * no VC is available
  577. * @return @li IX_FAIL
  578. * parameter error,
  579. * VC already in use,
  580. * attempt to connect AAL service on reserved OAM VPI/VCI,
  581. * attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI,
  582. * port is not initialised,
  583. * or some other error occurs during processing.
  584. *
  585. */
  586. PUBLIC IX_STATUS ixAtmdAccRxVcConnect (IxAtmLogicalPort port,
  587. unsigned int vpi,
  588. unsigned int vci,
  589. IxAtmdAccAalType aalServiceType,
  590. IxAtmRxQueueId rxQueueId,
  591. IxAtmdAccUserId userCallbackId,
  592. IxAtmdAccRxVcRxCallback rxCallback,
  593. unsigned int minimumReplenishCount,
  594. IxAtmConnId * connIdPtr,
  595. IxAtmNpeRxVcId * npeVcIdPtr );
  596. /**
  597. *
  598. * @ingroup IxAtmdAccAPI
  599. *
  600. * @fn ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
  601. IX_OSAL_MBUF * mbufPtr)
  602. *
  603. * @brief Provide free mbufs for data reception on a connection.
  604. *
  605. * This function provides mbufs for data reception by the hardware. This
  606. * function needs to be called by the user on a regular basis to ensure
  607. * no packet loss. Providing free buffers is a connection-based feature;
  608. * each connection can have different requirements in terms of buffer size
  609. * number of buffers, recycling rate. This function could be invoked from
  610. * within the context of a @a IxAtmdAccRxVcFreeLowCallback() callback
  611. * for a particular VC
  612. *
  613. * Mbufs provided through this function call can be chained. They will be
  614. * unchained internally. A call to this function with chained mbufs or
  615. * multiple calls with unchained mbufs are equivalent, but calls with
  616. * unchained mbufs are more efficients.
  617. *
  618. * Mbufs provided to this interface need to be able to hold at least one
  619. * full cell payload (48/52 bytes, depending on service type).
  620. * Chained buffers with a size less than the size supported by the hardware
  621. * will be returned through the rx callback provided during the connect step.
  622. *
  623. * Failing to invoke this function prior to enabling the RX traffic
  624. * can result in packet loss.
  625. *
  626. * This function is not reentrant for the same connId.
  627. *
  628. * This function does not use system resources and can be
  629. * invoked from an interrupt context.
  630. *
  631. * @note - Over replenish is detected, and extra mbufs are returned through
  632. * the rx callback provided during the connect step.
  633. *
  634. * @note - Mbuf provided to the replenish function should have a length greater or
  635. * equal to 48/52 bytes according to service type.
  636. *
  637. * @note - The memory cache of mMbuf payload should be invalidated prior to Mbuf
  638. * submission. Flushing the Mbuf headers is handled by IxAtmdAcc.
  639. *
  640. * @note - When a chained mbuf is provided, this function process the mbufs
  641. * up to the hardware limit and invokes the user-supplied callback
  642. * to release extra buffers.
  643. *
  644. * @sa ixAtmdAccRxVcFreeLowCallbackRegister
  645. * @sa IxAtmdAccRxVcFreeLowCallback
  646. * @sa ixAtmdAccRxVcConnect
  647. *
  648. * @param connId @ref IxAtmConnId [in] - connection Id as returned from a succesfull call to
  649. * @a IxAtmdAccRxVcConnect()
  650. * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a mbuf structure to be used for data
  651. * reception. The mbuf pointed to by this parameter can be chained
  652. * to an other mbuf.
  653. *
  654. * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcFreeReplenish()
  655. * and the mbuf is now ready to use for incoming traffic.
  656. * @return @li IX_ATMDACC_BUSY cannot process this request because
  657. * the max number of outstanding free buffers has been reached
  658. * or the internal resources have exhausted for this VC.
  659. * The user is responsible for retrying this request later.
  660. * @return @li IX_FAIL cannot process this request because of parameter
  661. * errors or some unspecified internal error has occurred.
  662. *
  663. * @note - It is not always guaranteed the replenish step to be as fast as the
  664. * hardware is consuming Rx Free mbufs. There is nothing in IxAtmdAcc to
  665. * guarantee that replenish reaches the rxFree threshold level. If the
  666. * threshold level is not reached, the next rxFree low notification for
  667. * this channel will not be triggered.
  668. * The preferred ways to replenish can be as follows (depending on
  669. * applications and implementations) :
  670. * @li Replenish in a rxFree low notification until the function
  671. * ixAtmdAccRxVcFreeReplenish() returns IX_ATMDACC_BUSY
  672. * @li Query the queue level using @sa ixAtmdAccRxVcFreeEntriesQuery, then
  673. * , replenish using @a ixAtmdAccRxVcFreeReplenish(), then query the queue
  674. * level again, and replenish if the threshold is still not reached.
  675. * @li Trigger replenish from an other event source and use rxFree starvation
  676. * to throttle the Rx traffic.
  677. *
  678. */
  679. PUBLIC IX_STATUS ixAtmdAccRxVcFreeReplenish (IxAtmConnId connId,
  680. IX_OSAL_MBUF * mbufPtr);
  681. /**
  682. *
  683. * @ingroup IxAtmdAccAPI
  684. *
  685. * @fn ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
  686. unsigned int numberOfMbufs,
  687. IxAtmdAccRxVcFreeLowCallback callback)
  688. *
  689. * @brief Configure the RX Free threshold value and register a callback
  690. * to handle threshold notifications.
  691. *
  692. * The function ixAtmdAccRxVcFreeLowCallbackRegister sets the threshold value for
  693. * a particular RX VC. When the number of buffers reaches this threshold
  694. * the callback is invoked.
  695. *
  696. * This function should be called once per VC before RX traffic is
  697. * enabled.This function will fail if the curent level of the free buffers
  698. * is equal or less than the threshold value.
  699. *
  700. * @sa ixAtmdAccRxVcFreeLowCallbackRegister
  701. * @sa IxAtmdAccRxVcFreeLowCallback
  702. * @sa ixAtmdAccRxVcFreeReplenish
  703. * @sa ixAtmdAccRxVcFreeEntriesQuery
  704. * @sa ixAtmdAccRxVcConnect
  705. *
  706. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
  707. * to @a IxAtmdAccRxVcConnect()
  708. * @param numberOfMbufs unsigned int [in] - threshold number of buffers. This number
  709. * has to be a power of 2, one of the values 0,1,2,4,8,16,32....
  710. * The maximum value cannot be more than half of the rxFree queue
  711. * size (which can be retrieved using @a ixAtmdAccRxVcFreeEntriesQuery()
  712. * before any use of the @a ixAtmdAccRxVcFreeReplenish() function)
  713. * @param callback @ref IxAtmdAccRxVcFreeLowCallback [in] - function telling the user that the number of
  714. * free buffers has reduced to the threshold value.
  715. *
  716. * @return @li IX_SUCCESS Threshold set successfully.
  717. * @return @li IX_FAIL parameter error or the current number of free buffers
  718. * is less than or equal to the threshold supplied or some
  719. * unspecified error has occrred.
  720. *
  721. * @note - the callback will be called when the threshold level will drop from
  722. * exactly (numberOfMbufs + 1) to (numberOfMbufs).
  723. *
  724. */
  725. PUBLIC IX_STATUS ixAtmdAccRxVcFreeLowCallbackRegister (IxAtmConnId connId,
  726. unsigned int numberOfMbufs,
  727. IxAtmdAccRxVcFreeLowCallback callback);
  728. /**
  729. *
  730. * @ingroup IxAtmdAccAPI
  731. *
  732. * @fn ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
  733. unsigned int *numberOfMbufsPtr)
  734. *
  735. * @brief Get the number of rx mbufs the system can accept to replenish the
  736. * the rx reception mechanism on a particular channel
  737. *
  738. * The ixAtmdAccRxVcFreeEntriesQuery function is used to retrieve the current
  739. * number of available mbuf entries for reception, on a per-VC basis. This
  740. * function can be used to know the number of mbufs which can be provided
  741. * using @a ixAtmdAccRxVcFreeReplenish().
  742. *
  743. * This function can be used from a timer context, or can be associated
  744. * with a threshold event, or can be used inside an active polling
  745. * mechanism which is under user control.
  746. *
  747. * This function is reentrant and does not use system resources and can
  748. * be invoked from an interrupt context.
  749. *
  750. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
  751. * to @a IxAtmdAccRxVcConnect()
  752. * @param numberOfMbufsPtr unsigned int [out] - Pointer to the number of available entries.
  753. * . This parameter cannot be a null pointer.
  754. *
  755. * @return @li IX_SUCCESS the current number of mbufs not yet used for incoming traffic
  756. * @return @li IX_FAIL invalid parameter
  757. *
  758. * @sa ixAtmdAccRxVcFreeReplenish
  759. *
  760. */
  761. PUBLIC IX_STATUS ixAtmdAccRxVcFreeEntriesQuery (IxAtmConnId connId,
  762. unsigned int *numberOfMbufsPtr);
  763. /**
  764. *
  765. * @ingroup IxAtmdAccAPI
  766. *
  767. * @fn ixAtmdAccRxVcEnable (IxAtmConnId connId)
  768. *
  769. * @brief Start the RX service on a VC.
  770. *
  771. * This functions kicks-off the traffic reception for a particular VC.
  772. * Once invoked, incoming PDUs will be made available by the hardware
  773. * and are eventually directed to the @a IxAtmdAccRxVcRxCallback() callback
  774. * registered for the connection.
  775. *
  776. * If the traffic is already running, this function returns IX_SUCCESS.
  777. * This function can be invoked many times.
  778. *
  779. * IxAtmdAccRxVcFreeLowCallback event will occur only after
  780. * @a ixAtmdAccRxVcEnable() function is invoked.
  781. *
  782. * Before using this function, the @a ixAtmdAccRxVcFreeReplenish() function
  783. * has to be used to replenish the RX Free queue. If not, incoming traffic
  784. * may be discarded.and in the case of interrupt driven reception the
  785. * @a IxAtmdAccRxVcFreeLowCallback() callback may be invoked as a side effect
  786. * during a replenish action.
  787. *
  788. * This function is not reentrant and should not be used inside an
  789. * interrupt context.
  790. *
  791. * For an VC connection this function can be called after a call to
  792. * @a ixAtmdAccRxVcDisable() and should not be called after
  793. * @a ixAtmdAccRxVcTryDisconnect()
  794. *
  795. * @sa ixAtmdAccRxVcDisable
  796. * @sa ixAtmdAccRxVcConnect
  797. * @sa ixAtmdAccRxVcFreeReplenish
  798. *
  799. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call
  800. * to @a IxAtmdAccRxVcConnect()
  801. *
  802. * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcEnable
  803. * @return @li IX_ATMDACC_WARNING the channel is already enabled
  804. * @return @li IX_FAIL invalid parameters or some unspecified internal
  805. * error occured.
  806. *
  807. */
  808. PUBLIC IX_STATUS ixAtmdAccRxVcEnable (IxAtmConnId connId);
  809. /**
  810. *
  811. * @ingroup IxAtmdAccAPI
  812. *
  813. * @fn ixAtmdAccRxVcDisable (IxAtmConnId connId)
  814. *
  815. * @brief Stop the RX service on a VC.
  816. *
  817. * This functions stops the traffic reception for a particular VC connection.
  818. *
  819. * Once invoked, incoming Pdus are discarded by the hardware. Any Pdus
  820. * pending will be freed to the user
  821. *
  822. * Hence once this function returns no more receive callbacks will be
  823. * called for that VC. However, buffer free callbacks will be invoked
  824. * until such time as all buffers supplied by the user have been freed
  825. * back to the user
  826. *
  827. * Calling this function doe not invalidate the connId.
  828. * @a ixAtmdAccRxVcEnable() can be invoked to enable Pdu reception again.
  829. *
  830. * If the traffic is already stopped, this function returns IX_SUCCESS.
  831. *
  832. * This function is not reentrant and should not be used inside an
  833. * interrupt context.
  834. *
  835. * @sa ixAtmdAccRxVcConnect
  836. * @sa ixAtmdAccRxVcEnable
  837. * @sa ixAtmdAccRxVcDisable
  838. *
  839. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to @a
  840. * IxAtmdAccRxVcConnect()
  841. *
  842. * @return @li IX_SUCCESS successful call to @a ixAtmdAccRxVcDisable().
  843. * @return @li IX_ATMDACC_WARNING the channel is already disabled
  844. * @return @li IX_FAIL invalid parameters or some unspecified internal error occured
  845. *
  846. */
  847. PUBLIC IX_STATUS ixAtmdAccRxVcDisable (IxAtmConnId connId);
  848. /**
  849. *
  850. * @ingroup IxAtmdAccAPI
  851. *
  852. * @fn ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId)
  853. *
  854. * @brief Disconnect a VC from the RX service.
  855. *
  856. * This function deregisters the VC and guarantees that all resources
  857. * associated with this VC are free. After its execution, the connection
  858. * Id is not available.
  859. *
  860. * This function will fail until such time as all resources allocated to
  861. * the VC connection have been freed. The user is responsible to delay and
  862. * call again this function many times until a success status is returned.
  863. *
  864. * This function needs internal locks and should not be called from an
  865. * interrupt context
  866. *
  867. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
  868. * @a IxAtmdAccRxVcConnect()
  869. *
  870. * @return @li IX_SUCCESS successful call to ixAtmdAccRxVcDisable
  871. * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
  872. * associated with the connection have been freed.
  873. * @return @li IX_FAIL cannot process this request because of a parameter
  874. * error
  875. *
  876. */
  877. PUBLIC IX_STATUS ixAtmdAccRxVcTryDisconnect (IxAtmConnId connId);
  878. /* ------------------------------------------------------
  879. Part of the IxAtmdAcc interface related to TX traffic
  880. ------------------------------------------------------ */
  881. /**
  882. *
  883. * @ingroup IxAtmdAccAPI
  884. *
  885. * @fn ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
  886. unsigned int vpi,
  887. unsigned int vci,
  888. IxAtmdAccAalType aalServiceType,
  889. IxAtmdAccUserId userId,
  890. IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
  891. IxAtmConnId * connIdPtr)
  892. *
  893. * @brief Connect to a Aal Pdu transmit service for a particular
  894. * port/vpi/vci and service type.
  895. *
  896. * This function allows a user to connect to an Aal5/Aal0/OAM Pdu transmit service
  897. * for a particular port/vpi/vci. It registers the callback and allocates
  898. * internal resources and a Connection Id to be used in further API calls
  899. * related to this VC.
  900. *
  901. * The function will setup VC transmit service on the specified on the
  902. * specified port. A connId is the reference by which IxAtmdAcc refers to a
  903. * connected VC. This identifier is the result of a succesful call
  904. * to a connect function. This identifier is invalid after a
  905. * sucessful call to a disconnect function.
  906. *
  907. * This function needs internal locks, and hence should not be called
  908. * from an interrupt context.
  909. *
  910. * On return from @a ixAtmdAccTxVcConnect() with a failure status, the
  911. * connection Id parameter is unspecified. Its value cannot be used.
  912. *
  913. * Calling this function for the same combination of port, Vpi, Vci and
  914. * more than once without calling @a ixAtmdAccTxVcTryDisconnect() will result
  915. * in a failure status.
  916. *
  917. * Two AAL0 services supporting 48 or 52 byte cell data are provided.
  918. * Submitted AAL0 PDUs must be a multiple of the cell data size (48/52).
  919. * AAL0_52 is a raw cell service the client must format
  920. * the PDU with an ATM cell header (excluding HEC) at the start of
  921. * each cell, note that AtmdAcc does not validate the cell headers in
  922. * a submitted PDU.
  923. *
  924. * For the OAM service an "OAM Tx channel" may be enabled for a port
  925. * by establishing a single dedicated OAM Tx connection on that port.
  926. *
  927. * The OAM service allows buffers containing 52 byte OAM F4/F5 cells
  928. * to be transmitted and received over the dedicated OAM channels.
  929. * HEC is appended/removed, and CRC-10 performed by the NPE. The OAM
  930. * service offered by AtmdAcc is a raw cell transport service.
  931. * It is assumed that ITU I.610 procedures that make use of this
  932. * service are implemented above AtmdAcc.
  933. *
  934. * Note that the dedicated OAM connections are established on
  935. * reserved VPI,VCI, and (in the case of Rx) port values.
  936. * These values are used purely to descriminate the dedicated OAM channels
  937. * and do not identify a particular OAM F4/F5 flow. F4/F5 flows may be
  938. * realised for particluar VPI/VCIs by manipulating the VPI,VCI
  939. * fields of the ATM cell headers of cells in the buffers passed
  940. * to AtmdAcc.
  941. *
  942. * Calling this function before enabling the port will fail.
  943. *
  944. * @sa ixAtmdAccTxVcTryDisconnect
  945. * @sa ixAtmdAccPortTxScheduledModeEnable
  946. * @sa ixAtmdAccPortEnable
  947. *
  948. * @param port @ref IxAtmLogicalPort [in] - VC identification : logical PHY port
  949. * [@a IX_UTOPIA_PORT_0 .. @a IX_UTOPIA_MAX_PORTS - 1]
  950. * @param vpi unsigned int [in] - VC identification : ATM Vpi [0..255] or IX_ATMDACC_OAM_VPI
  951. * @param vci unsigned int [in] - VC identification : ATM Vci [0..65535] or IX_ATMDACC_OAM_VCI
  952. * @param aalServiceType @ref IxAtmdAccAalType [in] - type of service AAL5, AAL0_48, AAL0_52, or OAM
  953. * @param userId @ref IxAtmdAccUserId [in] - user id to be used later during callbacks related
  954. * to this channel
  955. * @param bufferFreeCallback @ref IxAtmdAccTxVcBufferReturnCallback [in] - function called when mbufs
  956. * transmission is complete. This parameter cannot be a null
  957. * pointer.
  958. * @param connIdPtr @ref IxAtmConnId [out] - Pointer to a connection Id.
  959. * This parameter cannot be a null pointer.
  960. *
  961. * @return @li IX_SUCCESS successful call to @a IxAtmdAccRxVcConnect().
  962. * @return @li IX_ATMDACC_BUSY cannot process this request
  963. * because no VC is available
  964. * @return @li IX_FAIL
  965. * parameter error,
  966. * VC already in use,
  967. * attempt to connect AAL service on reserved OAM VPI/VCI,
  968. * attempt to connect OAM service on VPI/VCI other than the reserved OAM VPI/VCI,
  969. * port is not initialised,
  970. * or some other error occurs during processing.
  971. *
  972. * @note - Unscheduled mode is not supported in ixp425 1.0. Therefore, the
  973. * function @a ixAtmdAccPortTxScheduledModeEnable() need to be called
  974. * for this port before any establishing a Tx Connection
  975. */
  976. PUBLIC IX_STATUS ixAtmdAccTxVcConnect (IxAtmLogicalPort port,
  977. unsigned int vpi,
  978. unsigned int vci,
  979. IxAtmdAccAalType aalServiceType,
  980. IxAtmdAccUserId userId,
  981. IxAtmdAccTxVcBufferReturnCallback bufferFreeCallback,
  982. IxAtmConnId * connIdPtr);
  983. /**
  984. *
  985. * @ingroup IxAtmdAccAPI
  986. *
  987. * @fn ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
  988. IX_OSAL_MBUF * mbufPtr,
  989. IxAtmdAccClpStatus clp,
  990. unsigned int numberOfCells)
  991. *
  992. * @brief Submit a Pdu for transmission on connection.
  993. *
  994. * A data user calls this function to submit an mbufs containing a Pdu
  995. * to be transmitted. The buffer supplied can be chained and the Pdu it
  996. * contains must be complete.
  997. *
  998. * The transmission behavior of this call depends on the operational mode
  999. * of the port on which the connection is made.
  1000. *
  1001. * In unscheduled mode the mbuf will be submitted to the hardware
  1002. * immediately if sufficent resource is available. Otherwise the function
  1003. * will return failure.
  1004. *
  1005. * In scheduled mode the buffer is queued internally in IxAtmdAcc. The cell
  1006. * demand is made known to the traffic shaping entity. Cells from the
  1007. * buffers are MUXed onto the port some time later as dictated by the
  1008. * traffic shaping entity. The traffic shaping entity does this by sending
  1009. * transmit schedules to IxAtmdAcc via @a ixAtmdAccPortTxProcess() function call.
  1010. *
  1011. * Note that the dedicated OAM channel is scheduled just like any
  1012. * other channel. This means that any OAM traffic relating to an
  1013. * active AAL0/AAL5 connection will be scheduled independantly of the
  1014. * AAL0/AAL5 traffic for that connection.
  1015. *
  1016. * When transmission is complete, the TX Done mechanism will give the
  1017. * owmnership of these buffers back to the customer. The tx done mechanism
  1018. * must be in operation before transmission is attempted.
  1019. *
  1020. * For AAL0/OAM submitted AAL0 PDUs must be a multiple of the cell data
  1021. * size (48/52). AAL0_52 and OAM are raw cell services, and the client
  1022. * must format the PDU with an ATM cell header (excluding HEC) at the
  1023. * start of each cell, note that AtmdAcc does not validate the cell headers in
  1024. * a submitted PDU.
  1025. *
  1026. *
  1027. * @sa IxAtmdAccTxVcBufferReturnCallback
  1028. * @sa ixAtmdAccTxDoneDispatch
  1029. *
  1030. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
  1031. * @a ixAtmdAccTxVcConnect()
  1032. * @param mbufPtr @ref IX_OSAL_MBUF [in] - pointer to a chained structure of mbufs to transmit.
  1033. * This parameter cannot be a null pointer.
  1034. * @param clp @ref IxAtmdAccClpStatus [in] - clp indication for this PDU. All cells of this pdu
  1035. * will be sent with the clp bit set
  1036. * @param numberOfCells unsigned int [in] - number of cells in the PDU.
  1037. *
  1038. * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcPduSubmit()
  1039. * The pdu pointed by the mbufPtr parameter will be
  1040. * transmitted
  1041. * @return @li IX_ATMDACC_BUSY unable to process this request because
  1042. * internal resources are all used. The caller is responsible
  1043. * for retrying this request later.
  1044. * @return @li IX_FAIL unable to process this request because of error
  1045. * in the parameters (wrong connId supplied,
  1046. * or wrong mbuf pointer supplied), the total length of all buffers
  1047. * in the chain should be a multiple of the cell size
  1048. * ( 48/52 depending on the service type ),
  1049. * or unspecified error during processing
  1050. *
  1051. * @note - This function in not re-entrant for the same VC (e.g. : two
  1052. * thread cannot send PDUs for the same VC). But two threads can
  1053. * safely call this function with a different connection Id
  1054. *
  1055. * @note - In unscheduled mode, this function is not re-entrant on a per
  1056. * port basis. The size of pdus is limited to 8Kb.
  1057. *
  1058. * @note - 0-length mbufs should be removed from the chain before submission.
  1059. * The total length of the pdu (sdu + padding +trailer) has to be
  1060. * updated in the header of the first mbuf of a chain of mbufs.
  1061. *
  1062. * @note - Aal5 trailer information (UUI, CPI, SDU length) has to be supplied
  1063. * before submission.
  1064. *
  1065. * @note - The payload memory cache should be flushed, if needed, prior to
  1066. * transmission. Mbuf headers are flushed by IxAtmdAcc
  1067. *
  1068. * @note - This function does not use system resources and can be used
  1069. * inside an interrupt context
  1070. */
  1071. PUBLIC IX_STATUS ixAtmdAccTxVcPduSubmit (IxAtmConnId connId,
  1072. IX_OSAL_MBUF * mbufPtr,
  1073. IxAtmdAccClpStatus clp,
  1074. unsigned int numberOfCells);
  1075. /**
  1076. *
  1077. * @ingroup IxAtmdAccAPI
  1078. *
  1079. * @fn ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId)
  1080. *
  1081. * @brief Disconnect from a Aal Pdu transmit service for a particular
  1082. * port/vpi/vci.
  1083. *
  1084. * This function deregisters the VC and guarantees that all resources
  1085. * associated with this VC are free. After its execution, the connection
  1086. * Id is not available.
  1087. *
  1088. * This function will fail until such time as all resources allocated to
  1089. * the VC connection have been freed. The user is responsible to delay
  1090. * and call again this function many times until a success status is
  1091. * returned.
  1092. *
  1093. * After its execution, the connection Id is not available.
  1094. *
  1095. * @param connId @ref IxAtmConnId [in] - connection Id as resulted from a succesfull call to
  1096. * @a ixAtmdAccTxVcConnect()
  1097. *
  1098. * @return @li IX_SUCCESS successful call to @a ixAtmdAccTxVcTryDisconnect()
  1099. * @return @li IX_ATMDACC_RESOURCES_STILL_ALLOCATED not all resources
  1100. * associated with the connection have been freed. This condition will
  1101. * disappear after Tx and TxDone is complete for this channel.
  1102. * @return @li IX_FAIL unable to process this request because of errors
  1103. * in the parameters (wrong connId supplied)
  1104. *
  1105. * @note - This function needs internal locks and should not be called
  1106. * from an interrupt context
  1107. *
  1108. * @note - If the @a IX_ATMDACC_RESOURCES_STILL_ALLOCATED error does not
  1109. * clear after a while, this may be linked to a previous problem
  1110. * of cell overscheduling. Diabling the port and retry a disconnect
  1111. * will free the resources associated with this channel.
  1112. *
  1113. * @sa ixAtmdAccPortTxProcess
  1114. *
  1115. */
  1116. PUBLIC IX_STATUS ixAtmdAccTxVcTryDisconnect (IxAtmConnId connId);
  1117. #endif /* IXATMDACC_H */
  1118. /**
  1119. * @} defgroup IxAtmdAccAPI
  1120. */