source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxAtmSch.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 22 months ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 18.9 KB
Line 
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 * Redistribution and use in source and binary forms, with or without
29 * modification, are permitted provided that the following conditions
30 * are met:
31 * 1. Redistributions of source code must retain the above copyright
32 *    notice, this list of conditions and the following disclaimer.
33 * 2. Redistributions in binary form must reproduce the above copyright
34 *    notice, this list of conditions and the following disclaimer in the
35 *    documentation and/or other materials provided with the distribution.
36 * 3. Neither the name of the Intel Corporation nor the names of its contributors
37 *    may be used to endorse or promote products derived from this software
38 *    without specific prior written permission.
39 *
40 * @par
41 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
42 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
44 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
45 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
46 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
47 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
49 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
50 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 *
53 * @par
54 * -- End of Copyright Notice --
55 *
56 * @sa IxAtmm.h
57 *
58 */
59
60/**
61 * @defgroup IxAtmSch IXP400 ATM Transmit Scheduler (IxAtmSch) API
62 *
63 * @brief IXP400 ATM scheduler component Public API
64 *
65 * @{
66 */
67
68#ifndef IXATMSCH_H
69#define IXATMSCH_H
70
71#include "IxOsalTypes.h"
72#include "IxAtmTypes.h"
73
74/*
75 * #defines and macros used in this file.
76 */
77
78/* Return codes */
79
80/**
81 * @ingroup IxAtmSch
82 *
83 * @def IX_ATMSCH_RET_NOT_ADMITTED
84 * @brief Indicates that CAC function has rejected VC registration due
85 *         to insufficient line capacity.
86*/
87#define IX_ATMSCH_RET_NOT_ADMITTED 2
88
89/** 
90 * @ingroup IxAtmSch
91 *
92 * @def IX_ATMSCH_RET_QUEUE_FULL
93 *  @brief Indicates that the VC queue is full, no more demand can be
94 *         queued at this time.
95 */
96#define IX_ATMSCH_RET_QUEUE_FULL 3
97
98/** 
99 * @ingroup IxAtmSch
100 *
101 *  @def IX_ATMSCH_RET_QUEUE_EMPTY
102 *  @brief Indicates that all VC queues on this port are empty and
103 *         therefore there are no cells to be scheduled at this time.
104 */
105#define IX_ATMSCH_RET_QUEUE_EMPTY 4
106
107/*
108 * Function declarations
109 */
110
111/** 
112 * @ingroup IxAtmSch
113 *
114 * @fn ixAtmSchInit(void)
115 *
116 *  @brief This function is used to initialize the ixAtmSch component. It
117 *         should be called before any other IxAtmSch API function.
118 *
119 * @param None
120 *
121 * @return
122 * - <b>IX_SUCCESS :</b> indicates that
123 *          -# The ATM scheduler component has been successfully initialized.
124 *          -# The scheduler is ready to accept Port modelling requests.
125 * - <b>IX_FAIL :</b> Some internal error has prevented the scheduler component
126 *          from initialising.
127 */
128PUBLIC IX_STATUS
129ixAtmSchInit(void);
130
131/** 
132 * @ingroup IxAtmSch
133 *
134 * @fn ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
135                                       unsigned int portRate,
136                                       unsigned int minCellsToSchedule)
137 *
138 * @brief This function shall be called first to initialize an ATM port before
139 *         any other ixAtmSch API calls may be made for that port.
140 *
141 * @param port @ref IxAtmLogicalPort [in] - The specific port to initialize.  Valid
142 *          values range from 0 to IX_UTOPIA_MAX_PORTS - 1, representing a
143 *          maximum of IX_UTOPIA_MAX_PORTS possible ports.
144 *
145 * @param portRate unsigned int [in] - Value indicating the upstream capacity
146 *          of the indicated port.  The value should be supplied in
147 *          units of ATM (53 bytes) cells per second.
148 *          A port rate of 800Kbits/s is the equivalent
149 *          of 1886 cells per second
150 *
151 * @param minCellsToSchedule unsigned int [in] - This parameter specifies the minimum
152 *          number of cells which the scheduler will put in a schedule
153 *          table for this port. This value sets the worst case CDVT for VCs
154 *          on this port i.e. CDVT = 1*minCellsToSchedule/portRate.
155 * @return
156 *    - <b>IX_SUCCESS :</b> indicates that
157 *          -# The ATM scheduler has been successfully initialized.
158 *          -# The requested port model has been established.
159 *          -# The scheduler is ready to accept VC modelling requests
160 *            on the ATM port.
161 *    - <b>IX_FAIL :</b> indicates the requested port could not be
162 * initialized.  */
163PUBLIC IX_STATUS
164ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
165                                       unsigned int portRate,
166                                       unsigned int minCellsToSchedule);
167
168/** 
169 * @ingroup IxAtmSch
170 *
171 * @fn ixAtmSchPortRateModify( IxAtmLogicalPort port,
172                        unsigned int portRate)
173 *
174 *  @brief This function is called to modify the portRate on a
175 *         previously initialized port, typically in the event that
176 *         the line condition of the port changes.
177 *
178 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port which is to be
179 *          modified.
180 *
181 * @param portRate unsigned int [in] - Value indicating the new upstream
182 *          capacity for this port in cells/second.
183 *          A port rate of 800Kbits/s is the equivalent
184 *          of 1886 cells per second
185 *
186 * @return
187 * - <b>IX_SUCCESS :</b> The port rate has been successfully modified.<br>
188 * - <b>IX_FAIL :</b> The port rate could not be modified, either
189 *      because the input data was invalid, or the new port rate is
190 *      insufficient to support established ATM VC contracts on this
191 *      port.
192 *
193 * @warning The IxAtmSch component will validate the supplied port
194 *          rate is sufficient to support all established VC
195 *          contracts on the port.  If the new port rate is
196 *          insufficient to support all established contracts then
197 *          the request to modify the port rate will be rejected.
198 *          In this event, the user is expected to remove
199 *          established contracts using the ixAtmSchVcModelRemove
200 *          interface and then retry this interface.
201 *
202 * @sa ixAtmSchVcModelRemove() */
203PUBLIC IX_STATUS
204ixAtmSchPortRateModify( IxAtmLogicalPort port,
205                        unsigned int portRate);
206
207
208/** 
209 * @ingroup IxAtmSch
210 *
211 * @fn ixAtmSchVcModelSetup( IxAtmLogicalPort port,
212                      IxAtmTrafficDescriptor *trafficDesc,
213                      IxAtmSchedulerVcId *vcId)
214 *
215 *  @brief A client calls this interface to set up an upstream
216 *         (transmitting) virtual connection model (VC) on the
217 *         specified ATM port.  This function also provides the
218 *         virtual * connection admission control (CAC) service to the
219 *         client.
220 *
221 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
222 *          VC is to be established.
223 *
224 * @param *trafficDesc @ref IxAtmTrafficDescriptor [in] - Pointer to a structure
225 *          describing the requested traffic contract of the VC to be
226 *          established.  This structure contains the typical ATM
227 *          traffic descriptor values (e.g. PCR, SCR, MBS, CDVT, etc.)
228 *          defined by the ATM standard.
229 *
230 * @param *vcId @ref IxAtmSchedulerVcId [out] - This value will be filled with the
231 *              port-unique identifier for this virtual connection.  A
232 *              valid identification is a non-negative number.
233 *
234 * @return
235 * - <b>IX_SUCCESS :</b> The VC has been successfully established on
236 *      this port.  The client may begin to submit demand on this VC.
237 * - <b>IX_ATMSCH_RET_NOT_ADMITTED :</b> The VC cannot be established
238 *      on this port because there is insufficient upstream capacity
239 *      available to support the requested traffic contract descriptor
240 * - <b>IX_FAIL :</b>Input data are invalid.  VC has not been
241 *      established.
242 */
243PUBLIC IX_STATUS
244ixAtmSchVcModelSetup( IxAtmLogicalPort port,
245                      IxAtmTrafficDescriptor *trafficDesc,
246                      IxAtmSchedulerVcId *vcId);
247
248/** 
249 * @ingroup IxAtmSch
250 *
251 * @fn ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
252                     IxAtmSchedulerVcId vcId,
253                     IxAtmConnId vcUserConnId)
254 *
255 *  @brief A client calls this interface to set the vcUserConnId for a VC on
256 *         the specified ATM port. This vcUserConnId will default to
257 *         IX_ATM_IDLE_CELLS_CONNID if this function is not called for a VC.
258 *         Hence if the client does not call this function for a VC then only idle
259 *         cells will be scheduled for this VC.
260 *
261 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
262 *        VC is has been established.
263 *
264 * @param vcId @ref IxAtmSchedulerVcId [in] - This is the unique identifier for this virtual
265 *        connection. A valid identification is a non-negative number and is
266 *        all ports.
267 *
268 * @param vcUserConnId @ref IxAtmConnId [in] - The connId is used to refer to a VC in schedule
269 *        table entries. It is treated as the Id by which the scheduler client
270 *        knows the VC. It is used in any communicatations from the Scheduler
271 *        to the scheduler user e.g. schedule table entries.
272 *
273 * @return
274 * - <b>IX_SUCCESS :</b> The id has successfully been set.
275 * - <b>IX_FAIL :</b>Input data are invalid. connId id is not established.
276 */
277PUBLIC IX_STATUS
278ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
279                     IxAtmSchedulerVcId vcId,
280                     IxAtmConnId vcUserConnId);
281
282/** 
283 * @ingroup IxAtmSch
284 *
285 * @fn ixAtmSchVcModelRemove( IxAtmLogicalPort port,
286                       IxAtmSchedulerVcId vcId)
287 *
288 *  @brief Interface called by the client to remove a previously
289 *         established VC on a particular port.
290 *
291 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
292 *          removed is established.
293 *
294 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be removed.  This is the
295 *          value returned by the @ref ixAtmSchVcModelSetup call which
296 *          established the relevant VC.
297 *
298 * @return
299 * - <b>IX_SUCCESS :</b> The VC has been successfully removed from
300 *      this port. It is no longer modelled on this port.
301 * - <b>IX_FAIL :</b>Input data are invalid. The VC is still being modeled
302 *      by the traffic shaper.
303 *
304 * @sa ixAtmSchVcModelSetup()
305 */
306PUBLIC IX_STATUS
307ixAtmSchVcModelRemove( IxAtmLogicalPort port,
308                       IxAtmSchedulerVcId vcId);
309
310/** 
311 * @ingroup IxAtmSch
312 *
313 * @fn ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
314                       IxAtmSchedulerVcId vcId,
315                       unsigned int numberOfCells)
316 *
317 *  @brief The client calls this function to notify IxAtmSch that the
318 *         user of a VC has submitted cells for transmission.
319 *
320 *  This information is stored, aggregated from a number of calls to
321 *  ixAtmSchVcQueueUpdate and eventually used in the call to
322 *  ixAtmSchTableUpdate.
323 *
324 *  Normally IxAtmSch will update the VC queue by adding the number of
325 *  cells to the current queue length.  However, if IxAtmSch
326 *  determines that the user has over-submitted for the VC and
327 *  exceeded its transmission quota the queue request can be rejected.
328 *  The user should resubmit the request later when the queue has been
329 *  depleted.
330 *
331 *  This implementation of ixAtmSchVcQueueUpdate uses no operating
332 *  system or external facilities, either directly or indirectly.
333 *  This allows clients to call this function form within an interrupt handler.
334 *
335 *  This interface is structurally compatible with the
336 *  IxAtmdAccSchQueueUpdate callback type definition required for
337 *  IXP400 ATM scheduler interoperability.
338 *
339 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
340 *          updated is established.
341 *
342 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be updated.  This is the
343 *          value returned by the @ref ixAtmSchVcModelSetup call which
344 *          established the relevant VC.
345 *
346 * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should
347 *          be added to the queue for this VC.
348 *
349 * @return
350 *  - <b>IX_SUCCESS :</b> The VC queue has been successfully updated.
351 *  - <b>IX_ATMSCH_RET_QUEUE_FULL :</b> The VC queue has reached a
352 *       preset limit.  This indicates the client has over-submitted
353 *       and exceeded its transmission quota.  The request is
354 *       rejected.  The VC queue is not updated.  The VC user is
355 *       advised to resubmit the request later.
356 *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is updated.
357 *
358 * @warning IxAtmSch assumes that the calling software ensures that
359 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
360 *          ixAtmSchTableUpdate are both self and mutually exclusive
361 *          for the same port.
362 *
363 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
364PUBLIC IX_STATUS
365ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
366                       IxAtmSchedulerVcId vcId,
367                       unsigned int numberOfCells);
368
369/** 
370 * @ingroup IxAtmSch
371 *
372 * @fn ixAtmSchVcQueueClear( IxAtmLogicalPort port,
373                      IxAtmSchedulerVcId vcId)
374 *
375 *  @brief The client calls this function to remove all currently
376 *         queued cells from a registered VC.  The pending cell count
377 *         for the specified VC is reset to zero.
378 *
379 *  This interface is structurally compatible with the
380 *  IxAtmdAccSchQueueClear callback type definition required for
381 *  IXP400 ATM scheduler interoperability.
382 *
383 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
384 *          cleared is established.
385 *
386 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be cleared.  This is the
387 *          value returned by the @ref ixAtmSchVcModelSetup call which
388 *          established the relevant VC.
389 *
390 * @return
391 *  - <b>IX_SUCCESS :</b> The VC queue has been successfully cleared.
392 *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is modified.
393 *
394 * @warning IxAtmSch assumes that the calling software ensures that
395 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
396 *          ixAtmSchTableUpdate are both self and mutually exclusive
397 *          for the same port.
398 *
399 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
400PUBLIC IX_STATUS
401ixAtmSchVcQueueClear( IxAtmLogicalPort port,
402                      IxAtmSchedulerVcId vcId);
403
404/** 
405 * @ingroup IxAtmSch
406 *
407 * @fn ixAtmSchTableUpdate( IxAtmLogicalPort port,
408                     unsigned int maxCells,
409                     IxAtmScheduleTable **rettable)
410 *
411 *  @brief The client calls this function to request an update of the
412 *         schedule table for a particular ATM port.
413 *
414 *  This is called when the client decides it needs a new sequence of
415 *  cells to send (probably because the transmit queue is near to
416 *  empty for this ATM port).  The scheduler will use its stored
417 *  information on the cells submitted for transmit (i.e. data
418 *  supplied via @ref ixAtmSchVcQueueUpdate function) with the traffic
419 *  descriptor information of all established VCs on the ATM port to
420 *  decide the sequence of cells to be sent and fill the schedule
421 *  table for a period of time into the future.
422 *
423 *  IxAtmSch will guarantee a minimum of minCellsToSchedule if there
424 *  is at least one cell ready to send. If there are no cells then
425 *  IX_ATMSCH_RET_QUEUE_EMPTY is returned.
426 *
427 *  This implementation of ixAtmSchTableUpdate uses no operating
428 *  system or external facilities, either directly or indirectly.
429 *  This allows clients to call this function form within an FIQ
430 *  interrupt handler.
431 *
432 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port for which requested
433 *          schedule table is to be generated.
434 *
435 * @param maxCells unsigned [in] - Specifies the maximum number of cells
436 *          that must be scheduled in the supplied table during any
437 *          call to the interface.
438 *
439 * @param **table @ref IxAtmScheduleTable [out] - A pointer to an area of
440 *              storage is returned which contains the generated
441 *              schedule table.  The client should not modify the
442 *              contents of this table.
443 *
444 * @return
445 *  - <b>IX_SUCCESS :</b> The schedule table has been published.
446 *       Currently there is at least one VC queue that is nonempty.
447 *  - <b>IX_ATMSCH_RET_QUEUE_EMPTY :</b> Currently all VC queues on
448 *       this port are empty.  The schedule table returned is set to
449 *       NULL.  The client is not expected to invoke this function
450 *       again until more cells have been submitted on this port
451 *       through the @ref ixAtmSchVcQueueUpdate function.
452 *  - <b>IX_FAIL :</b> The input are invalid.  No action is taken.
453 *
454 * @warning IxAtmSch assumes that the calling software ensures that
455 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
456 *          ixAtmSchTableUpdate are both self and mutually exclusive
457 *          for the same port.
458 *
459 * @warning Subsequent calls to this function for the same port will
460 *          overwrite the contents of previously supplied schedule
461 *          tables.  The client must be completely finished with the
462 *          previously supplied schedule table before calling this
463 *          function again for the same port.
464 *
465 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
466PUBLIC IX_STATUS
467ixAtmSchTableUpdate( IxAtmLogicalPort port,
468                     unsigned int maxCells,
469                     IxAtmScheduleTable **rettable);
470
471/** 
472 * @ingroup IxAtmSch
473 *
474 * @fn ixAtmSchShow(void)
475 *
476 *  @brief Utility function which will print statistics on the current
477 *         and accumulated state of VCs and traffic in the ATM
478 *         scheduler component.  Output is sent to the default output
479 *         device.
480 *
481 * @param none
482 * @return none
483 */
484PUBLIC void
485ixAtmSchShow(void);
486
487/** 
488 * @ingroup IxAtmSch
489 *
490 * @fn ixAtmSchStatsClear(void)
491 *
492 *  @brief Utility function which will reset all counter statistics in
493 *         the ATM scheduler to zero.
494 *
495 * @param none
496 * @return none
497 */
498PUBLIC void
499ixAtmSchStatsClear(void);
500
501#endif
502/* IXATMSCH_H */
503
504/** @} */
Note: See TracBrowser for help on using the repository browser.