IxAtmm.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771
  1. /**
  2. * @file IxAtmm.h
  3. *
  4. * @date 3-DEC-2001
  5. *
  6. * @brief Header file for the IXP400 ATM Manager component (IxAtmm)
  7. *
  8. *
  9. * @par
  10. * IXP400 SW Release version 2.0
  11. *
  12. * -- Copyright Notice --
  13. *
  14. * @par
  15. * Copyright 2001-2005, Intel Corporation.
  16. * All rights reserved.
  17. *
  18. * @par
  19. * SPDX-License-Identifier: BSD-3-Clause
  20. * @par
  21. * -- End of Copyright Notice --
  22. */
  23. /**
  24. * @defgroup IxAtmm IXP400 ATM Manager (IxAtmm) API
  25. *
  26. * @brief IXP400 ATM Manager component Public API
  27. *
  28. * @{
  29. */
  30. #ifndef IXATMM_H
  31. #define IXATMM_H
  32. /*
  33. * Put the user defined include files required
  34. */
  35. #include "IxAtmSch.h"
  36. #include "IxOsalTypes.h"
  37. /*
  38. * #defines and macros used in this file.
  39. */
  40. /**
  41. * @def IX_ATMM_RET_ALREADY_INITIALIZED
  42. *
  43. * @brief Component has already been initialized
  44. */
  45. #define IX_ATMM_RET_ALREADY_INITIALIZED 2
  46. /**
  47. * @def IX_ATMM_RET_INVALID_PORT
  48. *
  49. * @brief Specified port does not exist or is out of range */
  50. #define IX_ATMM_RET_INVALID_PORT 3
  51. /**
  52. * @def IX_ATMM_RET_INVALID_VC_DESCRIPTOR
  53. *
  54. * @brief The VC description does not adhere to ATM standards */
  55. #define IX_ATMM_RET_INVALID_VC_DESCRIPTOR 4
  56. /**
  57. * @def IX_ATMM_RET_VC_CONFLICT
  58. *
  59. * @brief The VPI/VCI values supplied are either reserved, or they
  60. * conflict with a previously registered VC on this port */
  61. #define IX_ATMM_RET_VC_CONFLICT 5
  62. /**
  63. * @def IX_ATMM_RET_PORT_CAPACITY_IS_FULL
  64. *
  65. * @brief The virtual connection cannot be established on the port
  66. * because the remaining port capacity is not sufficient to
  67. * support it */
  68. #define IX_ATMM_RET_PORT_CAPACITY_IS_FULL 6
  69. /**
  70. * @def IX_ATMM_RET_NO_SUCH_VC
  71. *
  72. * @brief No registered VC, as described by the supplied VCI/VPI or
  73. * VC identifier values, exists on this port */
  74. #define IX_ATMM_RET_NO_SUCH_VC 7
  75. /**
  76. * @def IX_ATMM_RET_INVALID_VC_ID
  77. *
  78. * @brief The specified VC identifier is out of range. */
  79. #define IX_ATMM_RET_INVALID_VC_ID 8
  80. /**
  81. * @def IX_ATMM_RET_INVALID_PARAM_PTR
  82. *
  83. * @brief A pointer parameter was NULL. */
  84. #define IX_ATMM_RET_INVALID_PARAM_PTR 9
  85. /**
  86. * @def IX_ATMM_UTOPIA_SPHY_ADDR
  87. *
  88. * @brief The phy address when in SPHY mode */
  89. #define IX_ATMM_UTOPIA_SPHY_ADDR 31
  90. /**
  91. * @def IX_ATMM_THREAD_PRI_HIGH
  92. *
  93. * @brief The value of high priority thread */
  94. #define IX_ATMM_THREAD_PRI_HIGH 90
  95. /*
  96. * Typedefs whose scope is limited to this file.
  97. */
  98. /** @brief Definition for use in the @ref IxAtmmVc structure.
  99. * Indicates the direction of a VC */
  100. typedef enum
  101. {
  102. IX_ATMM_VC_DIRECTION_TX=0, /**< Atmm Vc direction transmit*/
  103. IX_ATMM_VC_DIRECTION_RX, /**< Atmm Vc direction receive*/
  104. IX_ATMM_VC_DIRECTION_INVALID /**< Atmm Vc direction invalid*/
  105. } IxAtmmVcDirection;
  106. /** @brief Definition for use with @ref IxAtmmVcChangeCallback
  107. * callback. Indicates that the event type represented by the
  108. * callback for this VC. */
  109. typedef enum
  110. {
  111. IX_ATMM_VC_CHANGE_EVENT_REGISTER=0, /**< Atmm Vc event register*/
  112. IX_ATMM_VC_CHANGE_EVENT_DEREGISTER, /**< Atmm Vc event de-register*/
  113. IX_ATMM_VC_CHANGE_EVENT_INVALID /**< Atmm Vc event invalid*/
  114. } IxAtmmVcChangeEvent;
  115. /** @brief Definitions for use with @ref ixAtmmUTOPIAInit interface to
  116. * indicate that UTOPIA loopback should be enabled or disabled
  117. * on initialisation. */
  118. typedef enum
  119. {
  120. IX_ATMM_UTOPIA_LOOPBACK_DISABLED=0, /**< Atmm Utopia loopback mode disabled*/
  121. IX_ATMM_UTOPIA_LOOPBACK_ENABLED, /**< Atmm Utopia loopback mode enabled*/
  122. IX_ATMM_UTOPIA_LOOPBACK_INVALID /**< Atmm Utopia loopback mode invalid*/
  123. } IxAtmmUtopiaLoopbackMode;
  124. /** @brief This structure describes the required attributes of a
  125. * virtual connection.
  126. */
  127. typedef struct {
  128. unsigned vpi; /**< VPI value of this virtual connection */
  129. unsigned vci; /**< VCI value of this virtual connection. */
  130. IxAtmmVcDirection direction; /**< VC direction */
  131. /** Traffic descriptor of this virtual connection. This structure
  132. * is defined by the @ref IxAtmSch component. */
  133. IxAtmTrafficDescriptor trafficDesc;
  134. } IxAtmmVc;
  135. /** @brief Definitions for use with @ref ixAtmmUtopiaInit interface to
  136. * indicate that UTOPIA multi-phy/single-phy mode is used.
  137. */
  138. typedef enum
  139. {
  140. IX_ATMM_MPHY_MODE = 0, /**< Atmm phy mode mphy*/
  141. IX_ATMM_SPHY_MODE, /**< Atmm phy mode sphy*/
  142. IX_ATMM_PHY_MODE_INVALID /**< Atmm phy mode invalid*/
  143. } IxAtmmPhyMode;
  144. /** @brief Structure contains port-specific information required to
  145. * initialize IxAtmm, and specifically, the IXP400 UTOPIA
  146. * Level-2 device. */
  147. typedef struct {
  148. unsigned reserved_1:11; /**< [31:21] Should be zero */
  149. unsigned UtopiaTxPhyAddr:5; /**< [20:16] Address of the
  150. * transmit (Tx) PHY for this
  151. * port on the 5-bit UTOPIA
  152. * Level-2 address bus */
  153. unsigned reserved_2:11; /**< [15:5] Should be zero */
  154. unsigned UtopiaRxPhyAddr:5; /**< [4:0] Address of the receive
  155. * (Rx) PHY for this port on the
  156. * 5-bit UTOPIA Level-2
  157. * address bus */
  158. } IxAtmmPortCfg;
  159. /** @brief Callback type used with @ref ixAtmmVcChangeCallbackRegister interface
  160. * Defines a callback type which will be used to notify registered
  161. * users of registration/deregistration events on a particular port
  162. *
  163. * @param eventType @ref IxAtmmVcChangeEvent [in] - Event indicating
  164. * whether the VC supplied has been added or
  165. * removed
  166. *
  167. * @param port @ref IxAtmLogicalPort [in] - Specifies the port on which the event has
  168. * occurred
  169. *
  170. * @param vcChanged @ref IxAtmmVc* [in] - Pointer to a structure which gives
  171. * details of the VC which has been added
  172. * or removed on the port
  173. */
  174. typedef void (*IxAtmmVcChangeCallback) (IxAtmmVcChangeEvent eventType,
  175. IxAtmLogicalPort port,
  176. const IxAtmmVc* vcChanged);
  177. /*
  178. * Variable declarations global to this file only. Externs are followed by
  179. * static variables.
  180. */
  181. /*
  182. * Extern function prototypes
  183. */
  184. /*
  185. * Function declarations
  186. */
  187. /**
  188. * @ingroup IxAtmm
  189. *
  190. * @fn ixAtmmInit (void)
  191. *
  192. * @brief Interface to initialize the IxAtmm software component. Can
  193. * be called once only.
  194. *
  195. * Must be called before any other IxAtmm API is called.
  196. *
  197. * @param "none"
  198. *
  199. * @return @li IX_SUCCESS : IxAtmm has been successfully initialized.
  200. * Calls to other IxAtmm interfaces may now be performed.
  201. * @return @li IX_FAIL : IxAtmm has already been initialized.
  202. */
  203. PUBLIC IX_STATUS
  204. ixAtmmInit (void);
  205. /**
  206. * @ingroup IxAtmm
  207. *
  208. * @fn ixAtmmUtopiaInit (unsigned numPorts,
  209. IxAtmmPhyMode phyMode,
  210. IxAtmmPortCfg portCfgs[],
  211. IxAtmmUtopiaLoopbackMode loopbackMode)
  212. *
  213. * @brief Interface to initialize the UTOPIA Level-2 ATM coprocessor
  214. * for the specified number of physical ports. The function
  215. * must be called before the ixAtmmPortInitialize interface
  216. * can operate successfully.
  217. *
  218. * @param numPorts unsigned [in] - Indicates the total number of logical
  219. * ports that are active on the device. Up to 12 ports are
  220. * supported.
  221. *
  222. * @param phyMode @ref IxAtmmPhyMode [in] - Put the Utopia coprocessor in SPHY
  223. * or MPHY mode.
  224. *
  225. * @param portCfgs[] @ref IxAtmmPortCfg [in] - Pointer to an array of elements
  226. * detailing the UTOPIA specific port characteristics. The
  227. * length of the array must be equal to the number of ports
  228. * activated. ATM ports are referred to by the relevant
  229. * offset in this array in all subsequent IxAtmm interface
  230. * calls.
  231. *
  232. * @param loopbackMode @ref IxAtmmUtopiaLoopbackMode [in] - Value must be one of
  233. * @ref IX_ATMM_UTOPIA_LOOPBACK_ENABLED or @ref
  234. * IX_ATMM_UTOPIA_LOOPBACK_DISABLED indicating whether
  235. * loopback should be enabled on the device. Loopback can
  236. * only be supported on a single PHY, therefore the numPorts
  237. * parameter must be 1 if loopback is enabled.
  238. *
  239. * @return @li IX_SUCCESS : Indicates that the UTOPIA device has been
  240. * successfully initialized for the supplied ports.
  241. * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : The UTOPIA device has
  242. * already been initialized.
  243. * @return @li IX_FAIL : The supplied parameters are invalid or have been
  244. * rejected by the UTOPIA-NPE device.
  245. *
  246. * @warning
  247. * This interface may only be called once.
  248. * Port identifiers are assumed to range from 0 to (numPorts - 1) in all
  249. * instances.
  250. * In all subsequent calls to interfaces supplied by IxAtmm, the specified
  251. * port value is expected to represent the offset in the portCfgs array
  252. * specified in this interface. i.e. The first port in this array will
  253. * subsequently be represented as port 0, the second port as port 1,
  254. * and so on.*/
  255. PUBLIC IX_STATUS
  256. ixAtmmUtopiaInit (unsigned numPorts,
  257. IxAtmmPhyMode phyMode,
  258. IxAtmmPortCfg portCfgs[],
  259. IxAtmmUtopiaLoopbackMode loopbackMode);
  260. /**
  261. * @ingroup IxAtmm
  262. *
  263. * @fn ixAtmmPortInitialize (IxAtmLogicalPort port,
  264. unsigned txPortRate,
  265. unsigned rxPortRate)
  266. *
  267. * @brief The interface is called following @ref ixAtmmUtopiaInit ()
  268. * and before calls to any other IxAtmm interface. It serves
  269. * to activate the registered ATM port with IxAtmm.
  270. *
  271. * The transmit and receive port rates are specified in bits per
  272. * second. This translates to ATM cells per second according to the
  273. * following formula: CellsPerSecond = portRate / (53*8) The
  274. * IXP400 device supports only 53 byte cells. The client shall make
  275. * sure that the off-chip physical layer device has already been
  276. * initialized.
  277. *
  278. * IxAtmm will configure IxAtmdAcc and IxAtmSch to enable scheduling
  279. * on the port.
  280. *
  281. * This interface must be called once for each active port in the
  282. * system. The first time the interface is invoked, it will configure
  283. * the mechanism by which the handling of transmit, transmit-done and
  284. * receive are driven with the IxAtmdAcc component.
  285. *
  286. * This function is reentrant.
  287. *
  288. * @note The minimum tx rate that will be accepted is 424 bit/s which equates
  289. * to 1 cell (53 bytes) per second.
  290. *
  291. * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be
  292. * initialized.
  293. *
  294. * @param txPortRate unsigned [in] - Value specifies the
  295. * transmit port rate for this port in
  296. * bits/second. This value is used by the ATM Scheduler
  297. * component is evaluating VC access requests for the port.
  298. *
  299. * @param rxPortRate unsigned [in] - Value specifies the
  300. * receive port rate for this port in bits/second.
  301. *
  302. * @return @li IX_SUCCESS : The specificed ATM port has been successfully
  303. * initialized. IxAtmm is ready to accept VC registrations on
  304. * this port.
  305. *
  306. * @return @li IX_ATMM_RET_ALREADY_INITIALIZED : ixAtmmPortInitialize has
  307. * already been called successfully on this port. The current
  308. * call is rejected.
  309. *
  310. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  311. * input is not valid. The request is rejected.
  312. *
  313. * @return @li IX_FAIL : IxAtmm could not initialize the port because the
  314. * inputs are not understood.
  315. *
  316. * @sa ixAtmmPortEnable, ixAtmmPortDisable
  317. *
  318. */
  319. PUBLIC IX_STATUS
  320. ixAtmmPortInitialize (IxAtmLogicalPort port,
  321. unsigned txPortRate,
  322. unsigned rxPortRate);
  323. /**
  324. * @ingroup IxAtmm
  325. *
  326. * @fn ixAtmmPortModify (IxAtmLogicalPort port,
  327. unsigned txPortRate,
  328. unsigned rxPortRate)
  329. *
  330. * @brief A client may call this interface to change the existing
  331. * port rate (expressed in bits/second) on an established ATM
  332. * port.
  333. *
  334. * @param port @ref IxAtmLogicalPort [in] - Identifies the port which is to be
  335. * initialized.
  336. *
  337. * @param txPortRate unsigned [in] - Value specifies the``
  338. * transmit port rate for this port in
  339. * bits/second. This value is used by the ATM Scheduler
  340. * component is evaluating VC access requests for the port.
  341. *
  342. * @param rxPortRate unsigned [in] - Value specifies the
  343. * receive port rate for this port in
  344. * bits/second.
  345. *
  346. * @return @li IX_SUCCESS : The indicated ATM port rates have been
  347. * successfully modified.
  348. *
  349. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  350. * input is not valid. The request is rejected.
  351. *
  352. * @return @li IX_FAIL : IxAtmm could not update the port because the
  353. * inputs are not understood, or the interface was called before
  354. * the port was initialized. */
  355. PUBLIC IX_STATUS
  356. ixAtmmPortModify (IxAtmLogicalPort port,
  357. unsigned txPortRate,
  358. unsigned rxPortRate);
  359. /**
  360. * @ingroup IxAtmm
  361. *
  362. * @fn ixAtmmPortQuery (IxAtmLogicalPort port,
  363. unsigned *txPortRate,
  364. unsigned *rxPortRate);
  365. *
  366. * @brief The client may call this interface to request details on
  367. * currently registered transmit and receive rates for an ATM
  368. * port.
  369. *
  370. * @param port @ref IxAtmLogicalPort [in] - Value identifies the port from which the
  371. * rate details are requested.
  372. *
  373. * @param *txPortRate unsigned [out] - Pointer to a value
  374. * which will be filled with the value of the transmit port
  375. * rate specified in bits/second.
  376. *
  377. * @param *rxPortRate unsigned [out] - Pointer to a value
  378. * which will be filled with the value of the receive port
  379. * rate specified in bits/second.
  380. *
  381. * @return @li IX_SUCCESS : The information requested on the specified
  382. * port has been successfully supplied in the output.
  383. *
  384. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  385. * input is not valid. The request is rejected.
  386. *
  387. * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
  388. * NULL.
  389. *
  390. * @return @li IX_FAIL : IxAtmm could not update the port because the
  391. * inputs are not understood, or the interface was called before
  392. * the port was initialized. */
  393. PUBLIC IX_STATUS
  394. ixAtmmPortQuery (IxAtmLogicalPort port,
  395. unsigned *txPortRate,
  396. unsigned *rxPortRate);
  397. /**
  398. * @ingroup IxAtmm
  399. *
  400. * @fn ixAtmmPortEnable(IxAtmLogicalPort port)
  401. *
  402. * @brief The client call this interface to enable transmit for an ATM
  403. * port. At initialisation, all the ports are disabled.
  404. *
  405. * @param port @ref IxAtmLogicalPort [in] - Value identifies the port
  406. *
  407. * @return @li IX_SUCCESS : Transmission over this port is started.
  408. *
  409. * @return @li IX_FAIL : The port parameter is not valid, or the
  410. * port is already enabled
  411. *
  412. * @note - When a port is disabled, Rx and Tx VC Connect requests will fail
  413. *
  414. * @note - This function uses system resources and should not be used
  415. * inside an interrupt context.
  416. *
  417. * @sa ixAtmmPortDisable */
  418. PUBLIC IX_STATUS
  419. ixAtmmPortEnable(IxAtmLogicalPort port);
  420. /**
  421. * @ingroup IxAtmm
  422. *
  423. * @fn ixAtmmPortDisable(IxAtmLogicalPort port)
  424. *
  425. * @brief The client call this interface to disable transmit for an ATM
  426. * port. At initialisation, all the ports are disabled.
  427. *
  428. * @param port @ref IxAtmLogicalPort [in] - Value identifies the port
  429. *
  430. * @return @li IX_SUCCESS : Transmission over this port is stopped.
  431. *
  432. * @return @li IX_FAIL : The port parameter is not valid, or the
  433. * port is already disabled
  434. *
  435. * @note - When a port is disabled, Rx and Tx VC Connect requests will fail
  436. *
  437. * @note - This function call does not stop RX traffic. It is supposed
  438. * that this function is invoked when a serious problem
  439. * is detected (e.g. physical layer broken). Then, the RX traffic
  440. * is not passing.
  441. *
  442. * @note - This function is blocking until the hw acknowledge that the
  443. * transmission is stopped.
  444. *
  445. * @note - This function uses system resources and should not be used
  446. * inside an interrupt context.
  447. *
  448. * @sa ixAtmmPortEnable */
  449. PUBLIC IX_STATUS
  450. ixAtmmPortDisable(IxAtmLogicalPort port);
  451. /**
  452. * @ingroup IxAtmm
  453. *
  454. * @fn ixAtmmVcRegister (IxAtmLogicalPort port,
  455. IxAtmmVc *vcToAdd,
  456. IxAtmSchedulerVcId *vcId)
  457. *
  458. * @brief This interface is used to register an ATM Virtual
  459. * Connection on the specified ATM port.
  460. *
  461. * Each call to this interface registers a unidirectional virtual
  462. * connection with the parameters specified. If a bi-directional VC
  463. * is needed, the function should be called twice (once for each
  464. * direction, Tx & Rx) where the VPI and VCI and port parameters in
  465. * each call are identical.
  466. *
  467. * With the addition of each new VC to a port, a series of
  468. * callback functions are invoked by the IxAtmm component to notify
  469. * possible external components of the change. The callback functions
  470. * are registered using the @ref ixAtmmVcChangeCallbackRegister interface.
  471. *
  472. * The IxAtmSch component is notified of the registration of transmit
  473. * VCs.
  474. *
  475. * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the specified VC is
  476. * to be registered.
  477. *
  478. * @param *vcToAdd @ref IxAtmmVc [in] - Pointer to an @ref IxAtmmVc structure
  479. * containing a description of the VC to be registered. The
  480. * client shall fill the vpi, vci and direction and relevant
  481. * trafficDesc members of this structure before calling this
  482. * function.
  483. *
  484. * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which is filled
  485. * with the per-port unique identifier value for this VC.
  486. * This identifier will be required when a request is
  487. * made to deregister or change this VC. VC identifiers
  488. * for transmit VCs will have a value between 0-43,
  489. * i.e. 32 data Tx VCs + 12 OAM Tx Port VCs.
  490. * Receive VCs will have a value between 44-66,
  491. * i.e. 32 data Rx VCs + 1 OAM Rx VC.
  492. *
  493. * @return @li IX_SUCCESS : The VC has been successfully registered on
  494. * this port. The VC is ready for a client to configure IxAtmdAcc
  495. * for receive and transmit operations on the VC.
  496. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  497. * input is not valid or has not been initialized. The request
  498. * is rejected.
  499. * @return @li IX_ATMM_RET_INVALID_VC_DESCRIPTOR : The descriptor
  500. * pointed to by vcToAdd is invalid. The registration request
  501. * is rejected.
  502. * @return @li IX_ATMM_RET_VC_CONFLICT : The VC requested conflicts with
  503. * reserved VPI and/or VCI values or with another VC already activated
  504. * on this port.
  505. * @return @li IX_ATMM_RET_PORT_CAPACITY_IS_FULL : The VC cannot be
  506. * registered in the port becuase the port capacity is
  507. * insufficient to support the requested ATM traffic contract.
  508. * The registration request is rejected.
  509. * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
  510. * NULL.
  511. *
  512. * @warning IxAtmm has no capability of signaling or negotiating a virtual
  513. * connection. Negotiation of the admission of the VC to the network
  514. * is beyond the scope of this function. This is assumed to be
  515. * performed by the calling client, if appropriate,
  516. * before or after this function is called.
  517. */
  518. PUBLIC IX_STATUS
  519. ixAtmmVcRegister (IxAtmLogicalPort port,
  520. IxAtmmVc *vcToAdd,
  521. IxAtmSchedulerVcId *vcId);
  522. /**
  523. * @ingroup IxAtmm
  524. *
  525. * @fn ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId)
  526. *
  527. * @brief Function called by a client to deregister a VC from the
  528. * system.
  529. *
  530. * With the removal of each new VC from a port, a series of
  531. * registered callback functions are invoked by the IxAtmm component
  532. * to notify possible external components of the change. The callback
  533. * functions are registered using the @ref ixAtmmVcChangeCallbackRegister.
  534. *
  535. * The IxAtmSch component is notified of the removal of transmit VCs.
  536. *
  537. * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
  538. * removed is currently registered.
  539. *
  540. * @param vcId @ref IxAtmSchedulerVcId [in] - VC identifier value of the VC to
  541. * be deregistered. This value was supplied to the client when
  542. the VC was originally registered. This value can also be
  543. queried from the IxAtmm component through the @ref ixAtmmVcQuery
  544. * interface.
  545. *
  546. * @return @li IX_SUCCESS : The specified VC has been successfully
  547. * removed from this port.
  548. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  549. * input is not valid or has not been initialized. The request
  550. * is rejected.
  551. * @return @li IX_FAIL : There is no registered VC associated with the
  552. * supplied identifier registered on this port. */
  553. PUBLIC IX_STATUS
  554. ixAtmmVcDeregister (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId);
  555. /**
  556. * @ingroup IxAtmm
  557. *
  558. * @fn ixAtmmVcQuery (IxAtmLogicalPort port,
  559. unsigned vpi,
  560. unsigned vci,
  561. IxAtmmVcDirection direction,
  562. IxAtmSchedulerVcId *vcId,
  563. IxAtmmVc *vcDesc)
  564. *
  565. * @brief This interface supplies information about an active VC on a
  566. * particular port when supplied with the VPI, VCI and
  567. * direction of that VC.
  568. *
  569. * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
  570. * queried is currently registered.
  571. *
  572. * @param vpi unsigned [in] - ATM VPI value of the requested VC.
  573. *
  574. * @param vci unsigned [in] - ATM VCI value of the requested VC.
  575. *
  576. * @param direction @ref IxAtmmVcDirection [in] - One of @ref
  577. * IX_ATMM_VC_DIRECTION_TX or @ref IX_ATMM_VC_DIRECTION_RX
  578. * indicating the direction (Tx or Rx) of the requested VC.
  579. *
  580. * @param *vcId @ref IxAtmSchedulerVcId [out] - Pointer to an integer value which will be
  581. * filled with the VC identifier value for the requested
  582. * VC (as returned by @ref ixAtmmVcRegister), if it
  583. * exists on this port.
  584. *
  585. * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure
  586. * which will be filled with the specific details of the
  587. * requested VC, if it exists on this port.
  588. *
  589. * @return @li IX_SUCCESS : The specified VC has been found on this port
  590. * and the requested details have been returned.
  591. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  592. * input is not valid or has not been initialized. The request
  593. * is rejected.
  594. * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified
  595. * port which matches the search criteria (VPI, VCI, direction)
  596. * given. No data is returned.
  597. * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
  598. * NULL.
  599. *
  600. */
  601. PUBLIC IX_STATUS
  602. ixAtmmVcQuery (IxAtmLogicalPort port,
  603. unsigned vpi,
  604. unsigned vci,
  605. IxAtmmVcDirection direction,
  606. IxAtmSchedulerVcId *vcId,
  607. IxAtmmVc *vcDesc);
  608. /**
  609. * @ingroup IxAtmm
  610. *
  611. * @fn ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc)
  612. *
  613. * @brief This interface supplies information about an active VC on a
  614. * particular port when supplied with a vcId for that VC.
  615. *
  616. * @param port @ref IxAtmLogicalPort [in] - Identifies port on which the VC to be
  617. * queried is currently registered.
  618. *
  619. * @param vcId @ref IxAtmSchedulerVcId [in] - Value returned by @ref ixAtmmVcRegister which
  620. * uniquely identifies the requested VC on this port.
  621. *
  622. * @param *vcDesc @ref IxAtmmVc [out] - Pointer to an @ref IxAtmmVc structure
  623. * which will be filled with the specific details of the
  624. * requested VC, if it exists on this port.
  625. *
  626. * @return @li IX_SUCCESS : The specified VC has been found on this port
  627. * and the requested details have been returned.
  628. * @return @li IX_ATMM_RET_INVALID_PORT : The port value indicated in the
  629. * input is not valid or has not been initialized. The request
  630. * is rejected.
  631. * @return @li IX_ATMM_RET_NO_SUCH_VC : No VC exists on the specified
  632. * port which matches the supplied identifier. No data is
  633. * returned.
  634. * @return @li IX_ATMM_RET_INVALID_PARAM_PTR : A pointer parameter was
  635. * NULL.
  636. */
  637. PUBLIC IX_STATUS
  638. ixAtmmVcIdQuery (IxAtmLogicalPort port, IxAtmSchedulerVcId vcId, IxAtmmVc *vcDesc);
  639. /**
  640. * @ingroup IxAtmm
  641. *
  642. * @fn ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback)
  643. *
  644. * @brief This interface is invoked to supply a function to IxAtmm
  645. * which will be called to notify the client if a new VC is
  646. * registered with IxAtmm or an existing VC is removed.
  647. *
  648. * The callback, when invoked, will run within the context of the call
  649. * to @ref ixAtmmVcRegister or @ref ixAtmmVcDeregister which caused
  650. * the change of state.
  651. *
  652. * A maximum of 32 calbacks may be registered in with IxAtmm.
  653. *
  654. * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies
  655. * with the @ref IxAtmmVcChangeCallback definition. This
  656. * function will be invoked by IxAtmm with the appropiate
  657. * parameters for the relevant VC when any VC has been
  658. * registered or deregistered with IxAtmm.
  659. *
  660. * @return @li IX_SUCCESS : The specified callback has been registered
  661. * successfully with IxAtmm and will be invoked when appropriate.
  662. * @return @li IX_FAIL : Either the supplied callback is invalid, or
  663. * IxAtmm has already registered 32 and connot accommodate
  664. * any further registrations of this type. The request is
  665. * rejected.
  666. *
  667. * @warning The client must not call either the @ref
  668. * ixAtmmVcRegister or @ref ixAtmmVcDeregister interfaces
  669. * from within the supplied callback function. */
  670. PUBLIC IX_STATUS ixAtmmVcChangeCallbackRegister (IxAtmmVcChangeCallback callback);
  671. /**
  672. * @ingroup IxAtmm
  673. *
  674. * @fn ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback)
  675. *
  676. * @brief This interface is invoked to deregister a previously supplied
  677. * callback function.
  678. *
  679. * @param callback @ref IxAtmmVcChangeCallback [in] - Callback which complies
  680. * with the @ref IxAtmmVcChangeCallback definition. This
  681. * function will removed from the table of callbacks.
  682. *
  683. * @return @li IX_SUCCESS : The specified callback has been deregistered
  684. * successfully from IxAtmm.
  685. * @return @li IX_FAIL : Either the supplied callback is invalid, or
  686. * is not currently registered with IxAtmm.
  687. */
  688. PUBLIC IX_STATUS
  689. ixAtmmVcChangeCallbackDeregister (IxAtmmVcChangeCallback callback);
  690. /**
  691. * @ingroup IxAtmm
  692. *
  693. * @fn ixAtmmUtopiaStatusShow (void)
  694. *
  695. * @brief Display utopia status counters
  696. *
  697. * @param "none"
  698. *
  699. * @return @li IX_SUCCESS : Show function was successful
  700. * @return @li IX_FAIL : Internal failure
  701. */
  702. PUBLIC IX_STATUS
  703. ixAtmmUtopiaStatusShow (void);
  704. /**
  705. * @ingroup IxAtmm
  706. *
  707. * @fn ixAtmmUtopiaCfgShow (void)
  708. *
  709. * @brief Display utopia information(config registers and status registers)
  710. *
  711. * @param "none"
  712. *
  713. * @return @li IX_SUCCESS : Show function was successful
  714. * @return @li IX_FAIL : Internal failure
  715. */
  716. PUBLIC IX_STATUS
  717. ixAtmmUtopiaCfgShow (void);
  718. #endif
  719. /* IXATMM_H */
  720. /** @} */