IxAtmSch.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480
  1. /**
  2. * @file IxAtmSch.h
  3. *
  4. * @date 23-NOV-2001
  5. *
  6. * @brief Header file for the IXP400 ATM Traffic Shaper
  7. *
  8. * This component demonstrates an ATM Traffic Shaper implementation. It
  9. * will perform shaping on upto 12 ports and total of 44 VCs accross all ports,
  10. * 32 are intended for AAL0/5 and 12 for OAM (1 per port).
  11. * The supported traffic types are;1 rt-VBR VC where PCR = SCR.
  12. * (Effectively CBR) and Up-to 44 VBR VCs.
  13. *
  14. * This component models the ATM ports and VCs and is capable of producing
  15. * a schedule of ATM cells per port which can be supplied to IxAtmdAcc
  16. * for execution on the data path.
  17. *
  18. * @par
  19. * IXP400 SW Release version 2.0
  20. *
  21. * -- Copyright Notice --
  22. *
  23. * @par
  24. * Copyright 2001-2005, Intel Corporation.
  25. * All rights reserved.
  26. *
  27. * @par
  28. * SPDX-License-Identifier: BSD-3-Clause
  29. * @par
  30. * -- End of Copyright Notice --
  31. *
  32. * @sa IxAtmm.h
  33. *
  34. */
  35. /**
  36. * @defgroup IxAtmSch IXP400 ATM Transmit Scheduler (IxAtmSch) API
  37. *
  38. * @brief IXP400 ATM scheduler component Public API
  39. *
  40. * @{
  41. */
  42. #ifndef IXATMSCH_H
  43. #define IXATMSCH_H
  44. #include "IxOsalTypes.h"
  45. #include "IxAtmTypes.h"
  46. /*
  47. * #defines and macros used in this file.
  48. */
  49. /* Return codes */
  50. /**
  51. * @ingroup IxAtmSch
  52. *
  53. * @def IX_ATMSCH_RET_NOT_ADMITTED
  54. * @brief Indicates that CAC function has rejected VC registration due
  55. * to insufficient line capacity.
  56. */
  57. #define IX_ATMSCH_RET_NOT_ADMITTED 2
  58. /**
  59. * @ingroup IxAtmSch
  60. *
  61. * @def IX_ATMSCH_RET_QUEUE_FULL
  62. * @brief Indicates that the VC queue is full, no more demand can be
  63. * queued at this time.
  64. */
  65. #define IX_ATMSCH_RET_QUEUE_FULL 3
  66. /**
  67. * @ingroup IxAtmSch
  68. *
  69. * @def IX_ATMSCH_RET_QUEUE_EMPTY
  70. * @brief Indicates that all VC queues on this port are empty and
  71. * therefore there are no cells to be scheduled at this time.
  72. */
  73. #define IX_ATMSCH_RET_QUEUE_EMPTY 4
  74. /*
  75. * Function declarations
  76. */
  77. /**
  78. * @ingroup IxAtmSch
  79. *
  80. * @fn ixAtmSchInit(void)
  81. *
  82. * @brief This function is used to initialize the ixAtmSch component. It
  83. * should be called before any other IxAtmSch API function.
  84. *
  85. * @param None
  86. *
  87. * @return
  88. * - <b>IX_SUCCESS :</b> indicates that
  89. * -# The ATM scheduler component has been successfully initialized.
  90. * -# The scheduler is ready to accept Port modelling requests.
  91. * - <b>IX_FAIL :</b> Some internal error has prevented the scheduler component
  92. * from initialising.
  93. */
  94. PUBLIC IX_STATUS
  95. ixAtmSchInit(void);
  96. /**
  97. * @ingroup IxAtmSch
  98. *
  99. * @fn ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
  100. unsigned int portRate,
  101. unsigned int minCellsToSchedule)
  102. *
  103. * @brief This function shall be called first to initialize an ATM port before
  104. * any other ixAtmSch API calls may be made for that port.
  105. *
  106. * @param port @ref IxAtmLogicalPort [in] - The specific port to initialize. Valid
  107. * values range from 0 to IX_UTOPIA_MAX_PORTS - 1, representing a
  108. * maximum of IX_UTOPIA_MAX_PORTS possible ports.
  109. *
  110. * @param portRate unsigned int [in] - Value indicating the upstream capacity
  111. * of the indicated port. The value should be supplied in
  112. * units of ATM (53 bytes) cells per second.
  113. * A port rate of 800Kbits/s is the equivalent
  114. * of 1886 cells per second
  115. *
  116. * @param minCellsToSchedule unsigned int [in] - This parameter specifies the minimum
  117. * number of cells which the scheduler will put in a schedule
  118. * table for this port. This value sets the worst case CDVT for VCs
  119. * on this port i.e. CDVT = 1*minCellsToSchedule/portRate.
  120. * @return
  121. * - <b>IX_SUCCESS :</b> indicates that
  122. * -# The ATM scheduler has been successfully initialized.
  123. * -# The requested port model has been established.
  124. * -# The scheduler is ready to accept VC modelling requests
  125. * on the ATM port.
  126. * - <b>IX_FAIL :</b> indicates the requested port could not be
  127. * initialized. */
  128. PUBLIC IX_STATUS
  129. ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
  130. unsigned int portRate,
  131. unsigned int minCellsToSchedule);
  132. /**
  133. * @ingroup IxAtmSch
  134. *
  135. * @fn ixAtmSchPortRateModify( IxAtmLogicalPort port,
  136. unsigned int portRate)
  137. *
  138. * @brief This function is called to modify the portRate on a
  139. * previously initialized port, typically in the event that
  140. * the line condition of the port changes.
  141. *
  142. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port which is to be
  143. * modified.
  144. *
  145. * @param portRate unsigned int [in] - Value indicating the new upstream
  146. * capacity for this port in cells/second.
  147. * A port rate of 800Kbits/s is the equivalent
  148. * of 1886 cells per second
  149. *
  150. * @return
  151. * - <b>IX_SUCCESS :</b> The port rate has been successfully modified.<br>
  152. * - <b>IX_FAIL :</b> The port rate could not be modified, either
  153. * because the input data was invalid, or the new port rate is
  154. * insufficient to support established ATM VC contracts on this
  155. * port.
  156. *
  157. * @warning The IxAtmSch component will validate the supplied port
  158. * rate is sufficient to support all established VC
  159. * contracts on the port. If the new port rate is
  160. * insufficient to support all established contracts then
  161. * the request to modify the port rate will be rejected.
  162. * In this event, the user is expected to remove
  163. * established contracts using the ixAtmSchVcModelRemove
  164. * interface and then retry this interface.
  165. *
  166. * @sa ixAtmSchVcModelRemove() */
  167. PUBLIC IX_STATUS
  168. ixAtmSchPortRateModify( IxAtmLogicalPort port,
  169. unsigned int portRate);
  170. /**
  171. * @ingroup IxAtmSch
  172. *
  173. * @fn ixAtmSchVcModelSetup( IxAtmLogicalPort port,
  174. IxAtmTrafficDescriptor *trafficDesc,
  175. IxAtmSchedulerVcId *vcId)
  176. *
  177. * @brief A client calls this interface to set up an upstream
  178. * (transmitting) virtual connection model (VC) on the
  179. * specified ATM port. This function also provides the
  180. * virtual * connection admission control (CAC) service to the
  181. * client.
  182. *
  183. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
  184. * VC is to be established.
  185. *
  186. * @param *trafficDesc @ref IxAtmTrafficDescriptor [in] - Pointer to a structure
  187. * describing the requested traffic contract of the VC to be
  188. * established. This structure contains the typical ATM
  189. * traffic descriptor values (e.g. PCR, SCR, MBS, CDVT, etc.)
  190. * defined by the ATM standard.
  191. *
  192. * @param *vcId @ref IxAtmSchedulerVcId [out] - This value will be filled with the
  193. * port-unique identifier for this virtual connection. A
  194. * valid identification is a non-negative number.
  195. *
  196. * @return
  197. * - <b>IX_SUCCESS :</b> The VC has been successfully established on
  198. * this port. The client may begin to submit demand on this VC.
  199. * - <b>IX_ATMSCH_RET_NOT_ADMITTED :</b> The VC cannot be established
  200. * on this port because there is insufficient upstream capacity
  201. * available to support the requested traffic contract descriptor
  202. * - <b>IX_FAIL :</b>Input data are invalid. VC has not been
  203. * established.
  204. */
  205. PUBLIC IX_STATUS
  206. ixAtmSchVcModelSetup( IxAtmLogicalPort port,
  207. IxAtmTrafficDescriptor *trafficDesc,
  208. IxAtmSchedulerVcId *vcId);
  209. /**
  210. * @ingroup IxAtmSch
  211. *
  212. * @fn ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
  213. IxAtmSchedulerVcId vcId,
  214. IxAtmConnId vcUserConnId)
  215. *
  216. * @brief A client calls this interface to set the vcUserConnId for a VC on
  217. * the specified ATM port. This vcUserConnId will default to
  218. * IX_ATM_IDLE_CELLS_CONNID if this function is not called for a VC.
  219. * Hence if the client does not call this function for a VC then only idle
  220. * cells will be scheduled for this VC.
  221. *
  222. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
  223. * VC is has been established.
  224. *
  225. * @param vcId @ref IxAtmSchedulerVcId [in] - This is the unique identifier for this virtual
  226. * connection. A valid identification is a non-negative number and is
  227. * all ports.
  228. *
  229. * @param vcUserConnId @ref IxAtmConnId [in] - The connId is used to refer to a VC in schedule
  230. * table entries. It is treated as the Id by which the scheduler client
  231. * knows the VC. It is used in any communicatations from the Scheduler
  232. * to the scheduler user e.g. schedule table entries.
  233. *
  234. * @return
  235. * - <b>IX_SUCCESS :</b> The id has successfully been set.
  236. * - <b>IX_FAIL :</b>Input data are invalid. connId id is not established.
  237. */
  238. PUBLIC IX_STATUS
  239. ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
  240. IxAtmSchedulerVcId vcId,
  241. IxAtmConnId vcUserConnId);
  242. /**
  243. * @ingroup IxAtmSch
  244. *
  245. * @fn ixAtmSchVcModelRemove( IxAtmLogicalPort port,
  246. IxAtmSchedulerVcId vcId)
  247. *
  248. * @brief Interface called by the client to remove a previously
  249. * established VC on a particular port.
  250. *
  251. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
  252. * removed is established.
  253. *
  254. * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be removed. This is the
  255. * value returned by the @ref ixAtmSchVcModelSetup call which
  256. * established the relevant VC.
  257. *
  258. * @return
  259. * - <b>IX_SUCCESS :</b> The VC has been successfully removed from
  260. * this port. It is no longer modelled on this port.
  261. * - <b>IX_FAIL :</b>Input data are invalid. The VC is still being modeled
  262. * by the traffic shaper.
  263. *
  264. * @sa ixAtmSchVcModelSetup()
  265. */
  266. PUBLIC IX_STATUS
  267. ixAtmSchVcModelRemove( IxAtmLogicalPort port,
  268. IxAtmSchedulerVcId vcId);
  269. /**
  270. * @ingroup IxAtmSch
  271. *
  272. * @fn ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
  273. IxAtmSchedulerVcId vcId,
  274. unsigned int numberOfCells)
  275. *
  276. * @brief The client calls this function to notify IxAtmSch that the
  277. * user of a VC has submitted cells for transmission.
  278. *
  279. * This information is stored, aggregated from a number of calls to
  280. * ixAtmSchVcQueueUpdate and eventually used in the call to
  281. * ixAtmSchTableUpdate.
  282. *
  283. * Normally IxAtmSch will update the VC queue by adding the number of
  284. * cells to the current queue length. However, if IxAtmSch
  285. * determines that the user has over-submitted for the VC and
  286. * exceeded its transmission quota the queue request can be rejected.
  287. * The user should resubmit the request later when the queue has been
  288. * depleted.
  289. *
  290. * This implementation of ixAtmSchVcQueueUpdate uses no operating
  291. * system or external facilities, either directly or indirectly.
  292. * This allows clients to call this function form within an interrupt handler.
  293. *
  294. * This interface is structurally compatible with the
  295. * IxAtmdAccSchQueueUpdate callback type definition required for
  296. * IXP400 ATM scheduler interoperability.
  297. *
  298. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
  299. * updated is established.
  300. *
  301. * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be updated. This is the
  302. * value returned by the @ref ixAtmSchVcModelSetup call which
  303. * established the relevant VC.
  304. *
  305. * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should
  306. * be added to the queue for this VC.
  307. *
  308. * @return
  309. * - <b>IX_SUCCESS :</b> The VC queue has been successfully updated.
  310. * - <b>IX_ATMSCH_RET_QUEUE_FULL :</b> The VC queue has reached a
  311. * preset limit. This indicates the client has over-submitted
  312. * and exceeded its transmission quota. The request is
  313. * rejected. The VC queue is not updated. The VC user is
  314. * advised to resubmit the request later.
  315. * - <b>IX_FAIL :</b> The input are invalid. No VC queue is updated.
  316. *
  317. * @warning IxAtmSch assumes that the calling software ensures that
  318. * calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
  319. * ixAtmSchTableUpdate are both self and mutually exclusive
  320. * for the same port.
  321. *
  322. * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
  323. PUBLIC IX_STATUS
  324. ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
  325. IxAtmSchedulerVcId vcId,
  326. unsigned int numberOfCells);
  327. /**
  328. * @ingroup IxAtmSch
  329. *
  330. * @fn ixAtmSchVcQueueClear( IxAtmLogicalPort port,
  331. IxAtmSchedulerVcId vcId)
  332. *
  333. * @brief The client calls this function to remove all currently
  334. * queued cells from a registered VC. The pending cell count
  335. * for the specified VC is reset to zero.
  336. *
  337. * This interface is structurally compatible with the
  338. * IxAtmdAccSchQueueClear callback type definition required for
  339. * IXP400 ATM scheduler interoperability.
  340. *
  341. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
  342. * cleared is established.
  343. *
  344. * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be cleared. This is the
  345. * value returned by the @ref ixAtmSchVcModelSetup call which
  346. * established the relevant VC.
  347. *
  348. * @return
  349. * - <b>IX_SUCCESS :</b> The VC queue has been successfully cleared.
  350. * - <b>IX_FAIL :</b> The input are invalid. No VC queue is modified.
  351. *
  352. * @warning IxAtmSch assumes that the calling software ensures that
  353. * calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
  354. * ixAtmSchTableUpdate are both self and mutually exclusive
  355. * for the same port.
  356. *
  357. * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
  358. PUBLIC IX_STATUS
  359. ixAtmSchVcQueueClear( IxAtmLogicalPort port,
  360. IxAtmSchedulerVcId vcId);
  361. /**
  362. * @ingroup IxAtmSch
  363. *
  364. * @fn ixAtmSchTableUpdate( IxAtmLogicalPort port,
  365. unsigned int maxCells,
  366. IxAtmScheduleTable **rettable)
  367. *
  368. * @brief The client calls this function to request an update of the
  369. * schedule table for a particular ATM port.
  370. *
  371. * This is called when the client decides it needs a new sequence of
  372. * cells to send (probably because the transmit queue is near to
  373. * empty for this ATM port). The scheduler will use its stored
  374. * information on the cells submitted for transmit (i.e. data
  375. * supplied via @ref ixAtmSchVcQueueUpdate function) with the traffic
  376. * descriptor information of all established VCs on the ATM port to
  377. * decide the sequence of cells to be sent and fill the schedule
  378. * table for a period of time into the future.
  379. *
  380. * IxAtmSch will guarantee a minimum of minCellsToSchedule if there
  381. * is at least one cell ready to send. If there are no cells then
  382. * IX_ATMSCH_RET_QUEUE_EMPTY is returned.
  383. *
  384. * This implementation of ixAtmSchTableUpdate uses no operating
  385. * system or external facilities, either directly or indirectly.
  386. * This allows clients to call this function form within an FIQ
  387. * interrupt handler.
  388. *
  389. * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port for which requested
  390. * schedule table is to be generated.
  391. *
  392. * @param maxCells unsigned [in] - Specifies the maximum number of cells
  393. * that must be scheduled in the supplied table during any
  394. * call to the interface.
  395. *
  396. * @param **table @ref IxAtmScheduleTable [out] - A pointer to an area of
  397. * storage is returned which contains the generated
  398. * schedule table. The client should not modify the
  399. * contents of this table.
  400. *
  401. * @return
  402. * - <b>IX_SUCCESS :</b> The schedule table has been published.
  403. * Currently there is at least one VC queue that is nonempty.
  404. * - <b>IX_ATMSCH_RET_QUEUE_EMPTY :</b> Currently all VC queues on
  405. * this port are empty. The schedule table returned is set to
  406. * NULL. The client is not expected to invoke this function
  407. * again until more cells have been submitted on this port
  408. * through the @ref ixAtmSchVcQueueUpdate function.
  409. * - <b>IX_FAIL :</b> The input are invalid. No action is taken.
  410. *
  411. * @warning IxAtmSch assumes that the calling software ensures that
  412. * calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
  413. * ixAtmSchTableUpdate are both self and mutually exclusive
  414. * for the same port.
  415. *
  416. * @warning Subsequent calls to this function for the same port will
  417. * overwrite the contents of previously supplied schedule
  418. * tables. The client must be completely finished with the
  419. * previously supplied schedule table before calling this
  420. * function again for the same port.
  421. *
  422. * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate(). */
  423. PUBLIC IX_STATUS
  424. ixAtmSchTableUpdate( IxAtmLogicalPort port,
  425. unsigned int maxCells,
  426. IxAtmScheduleTable **rettable);
  427. /**
  428. * @ingroup IxAtmSch
  429. *
  430. * @fn ixAtmSchShow(void)
  431. *
  432. * @brief Utility function which will print statistics on the current
  433. * and accumulated state of VCs and traffic in the ATM
  434. * scheduler component. Output is sent to the default output
  435. * device.
  436. *
  437. * @param none
  438. * @return none
  439. */
  440. PUBLIC void
  441. ixAtmSchShow(void);
  442. /**
  443. * @ingroup IxAtmSch
  444. *
  445. * @fn ixAtmSchStatsClear(void)
  446. *
  447. * @brief Utility function which will reset all counter statistics in
  448. * the ATM scheduler to zero.
  449. *
  450. * @param none
  451. * @return none
  452. */
  453. PUBLIC void
  454. ixAtmSchStatsClear(void);
  455. #endif
  456. /* IXATMSCH_H */
  457. /** @} */