summaryrefslogtreecommitdiff
path: root/cpu/ixp/npe/include/IxAtmSch.h
blob: 73c3be29abab93d41879dfdebf42baef4d2b37d4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
/**
 * @file    IxAtmSch.h
 *
 * @date    23-NOV-2001
 *
 * @brief   Header file for the IXP400 ATM Traffic Shaper
 *
 * This component demonstrates an ATM Traffic Shaper implementation. It
 * will perform shaping on upto 12 ports and total of 44 VCs accross all ports,
 * 32 are intended for AAL0/5 and 12 for OAM (1 per port).
 * The supported traffic types are;1 rt-VBR VC where PCR = SCR.
 * (Effectively CBR) and Up-to 44 VBR VCs.
 *
 * This component models the ATM ports and VCs and is capable of producing
 * a schedule of ATM cells per port which can be supplied to IxAtmdAcc
 * for execution on the data path.
 * 
 * @par
 * IXP400 SW Release version 2.0
 * 
 * -- Copyright Notice --
 * 
 * @par
 * Copyright 2001-2005, Intel Corporation.
 * All rights reserved.
 * 
 * @par
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Intel Corporation nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 * @par
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * @par
 * -- End of Copyright Notice --
 *
 * @sa IxAtmm.h
 *
 */

/**
 * @defgroup IxAtmSch IXP400 ATM Transmit Scheduler (IxAtmSch) API
 *
 * @brief IXP400 ATM scheduler component Public API
 *
 * @{
 */

#ifndef IXATMSCH_H
#define IXATMSCH_H

#include "IxOsalTypes.h"
#include "IxAtmTypes.h"

/*
 * #defines and macros used in this file.
 */

/* Return codes */

/** 
 * @ingroup IxAtmSch
 *
 * @def IX_ATMSCH_RET_NOT_ADMITTED
 * @brief Indicates that CAC function has rejected VC registration due
 *         to insufficient line capacity.
*/
#define IX_ATMSCH_RET_NOT_ADMITTED 2

/**  
 * @ingroup IxAtmSch
 *
 * @def IX_ATMSCH_RET_QUEUE_FULL
 *  @brief Indicates that the VC queue is full, no more demand can be
 *         queued at this time.
 */
#define IX_ATMSCH_RET_QUEUE_FULL 3

/**  
 * @ingroup IxAtmSch
 *
 *  @def IX_ATMSCH_RET_QUEUE_EMPTY
 *  @brief Indicates that all VC queues on this port are empty and
 *         therefore there are no cells to be scheduled at this time.
 */
#define IX_ATMSCH_RET_QUEUE_EMPTY 4

/*
 * Function declarations
 */

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchInit(void)
 *
 *  @brief This function is used to initialize the ixAtmSch component. It
 *         should be called before any other IxAtmSch API function.
 *
 * @param None
 *
 * @return
 * - <b>IX_SUCCESS :</b> indicates that
 *          -# The ATM scheduler component has been successfully initialized.
 *          -# The scheduler is ready to accept Port modelling requests.
 * - <b>IX_FAIL :</b> Some internal error has prevented the scheduler component
 *          from initialising.
 */
PUBLIC IX_STATUS
ixAtmSchInit(void);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
                                       unsigned int portRate,
                                       unsigned int minCellsToSchedule)
 *
 * @brief This function shall be called first to initialize an ATM port before
 *         any other ixAtmSch API calls may be made for that port.
 *
 * @param port @ref IxAtmLogicalPort [in] - The specific port to initialize.  Valid
 *          values range from 0 to IX_UTOPIA_MAX_PORTS - 1, representing a 
 *          maximum of IX_UTOPIA_MAX_PORTS possible ports.
 *
 * @param portRate unsigned int [in] - Value indicating the upstream capacity
 *          of the indicated port.  The value should be supplied in
 *          units of ATM (53 bytes) cells per second.
 *          A port rate of 800Kbits/s is the equivalent 
 *          of 1886 cells per second
 *
 * @param minCellsToSchedule unsigned int [in] - This parameter specifies the minimum
 *          number of cells which the scheduler will put in a schedule
 *          table for this port. This value sets the worst case CDVT for VCs
 *          on this port i.e. CDVT = 1*minCellsToSchedule/portRate.
 * @return
 *    - <b>IX_SUCCESS :</b> indicates that
 *          -# The ATM scheduler has been successfully initialized.
 *          -# The requested port model has been established.
 *          -# The scheduler is ready to accept VC modelling requests
 *            on the ATM port.
 *    - <b>IX_FAIL :</b> indicates the requested port could not be
 * initialized.  */
PUBLIC IX_STATUS
ixAtmSchPortModelInitialize( IxAtmLogicalPort port,
                                       unsigned int portRate,
                                       unsigned int minCellsToSchedule);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchPortRateModify( IxAtmLogicalPort port,
                        unsigned int portRate)
 *
 *  @brief This function is called to modify the portRate on a
 *         previously initialized port, typically in the event that
 *         the line condition of the port changes.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port which is to be
 *          modified.
 *
 * @param portRate unsigned int [in] - Value indicating the new upstream
 *          capacity for this port in cells/second.
 *          A port rate of 800Kbits/s is the equivalent 
 *          of 1886 cells per second
 *
 * @return
 * - <b>IX_SUCCESS :</b> The port rate has been successfully modified.<br>
 * - <b>IX_FAIL :</b> The port rate could not be modified, either
 *      because the input data was invalid, or the new port rate is
 *      insufficient to support established ATM VC contracts on this
 *      port.
 *
 * @warning The IxAtmSch component will validate the supplied port
 *          rate is sufficient to support all established VC
 *          contracts on the port.  If the new port rate is
 *          insufficient to support all established contracts then
 *          the request to modify the port rate will be rejected.
 *          In this event, the user is expected to remove
 *          established contracts using the ixAtmSchVcModelRemove
 *          interface and then retry this interface.
 *
 * @sa ixAtmSchVcModelRemove() */
PUBLIC IX_STATUS
ixAtmSchPortRateModify( IxAtmLogicalPort port,
                        unsigned int portRate);


/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcModelSetup( IxAtmLogicalPort port,
                      IxAtmTrafficDescriptor *trafficDesc,
                      IxAtmSchedulerVcId *vcId)
 *
 *  @brief A client calls this interface to set up an upstream
 *         (transmitting) virtual connection model (VC) on the
 *         specified ATM port.  This function also provides the
 *         virtual * connection admission control (CAC) service to the
 *         client.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
 *          VC is to be established.
 *
 * @param *trafficDesc @ref IxAtmTrafficDescriptor [in] - Pointer to a structure
 *          describing the requested traffic contract of the VC to be
 *          established.  This structure contains the typical ATM
 *          traffic descriptor values (e.g. PCR, SCR, MBS, CDVT, etc.)
 *          defined by the ATM standard.
 *
 * @param *vcId @ref IxAtmSchedulerVcId [out] - This value will be filled with the
 *              port-unique identifier for this virtual connection.  A
 *              valid identification is a non-negative number.
 *
 * @return
 * - <b>IX_SUCCESS :</b> The VC has been successfully established on
 *      this port.  The client may begin to submit demand on this VC.
 * - <b>IX_ATMSCH_RET_NOT_ADMITTED :</b> The VC cannot be established
 *      on this port because there is insufficient upstream capacity
 *      available to support the requested traffic contract descriptor
 * - <b>IX_FAIL :</b>Input data are invalid.  VC has not been
 *      established.
 */
PUBLIC IX_STATUS
ixAtmSchVcModelSetup( IxAtmLogicalPort port,
                      IxAtmTrafficDescriptor *trafficDesc,
                      IxAtmSchedulerVcId *vcId);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
                     IxAtmSchedulerVcId vcId,
                     IxAtmConnId vcUserConnId)
 *
 *  @brief A client calls this interface to set the vcUserConnId for a VC on
 *         the specified ATM port. This vcUserConnId will default to
 *         IX_ATM_IDLE_CELLS_CONNID if this function is not called for a VC.
 *         Hence if the client does not call this function for a VC then only idle
 *         cells will be scheduled for this VC.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the upstream
 *        VC is has been established.
 *
 * @param vcId @ref IxAtmSchedulerVcId [in] - This is the unique identifier for this virtual
 *        connection. A valid identification is a non-negative number and is
 *        all ports.
 *
 * @param vcUserConnId @ref IxAtmConnId [in] - The connId is used to refer to a VC in schedule
 *        table entries. It is treated as the Id by which the scheduler client
 *        knows the VC. It is used in any communicatations from the Scheduler
 *        to the scheduler user e.g. schedule table entries.
 *
 * @return
 * - <b>IX_SUCCESS :</b> The id has successfully been set.
 * - <b>IX_FAIL :</b>Input data are invalid. connId id is not established.
 */
PUBLIC IX_STATUS
ixAtmSchVcConnIdSet( IxAtmLogicalPort port,
                     IxAtmSchedulerVcId vcId,
                     IxAtmConnId vcUserConnId);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcModelRemove( IxAtmLogicalPort port,
                       IxAtmSchedulerVcId vcId)
 *
 *  @brief Interface called by the client to remove a previously
 *         established VC on a particular port.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 *          removed is established.
 *
 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be removed.  This is the
 *          value returned by the @ref ixAtmSchVcModelSetup call which
 *          established the relevant VC.
 *
 * @return
 * - <b>IX_SUCCESS :</b> The VC has been successfully removed from
 *      this port. It is no longer modelled on this port.
 * - <b>IX_FAIL :</b>Input data are invalid. The VC is still being modeled
 *      by the traffic shaper.
 *
 * @sa ixAtmSchVcModelSetup() 
 */
PUBLIC IX_STATUS
ixAtmSchVcModelRemove( IxAtmLogicalPort port,
                       IxAtmSchedulerVcId vcId);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
                       IxAtmSchedulerVcId vcId,
                       unsigned int numberOfCells)
 *
 *  @brief The client calls this function to notify IxAtmSch that the
 *         user of a VC has submitted cells for transmission.
 *
 *  This information is stored, aggregated from a number of calls to
 *  ixAtmSchVcQueueUpdate and eventually used in the call to
 *  ixAtmSchTableUpdate.
 *
 *  Normally IxAtmSch will update the VC queue by adding the number of
 *  cells to the current queue length.  However, if IxAtmSch
 *  determines that the user has over-submitted for the VC and
 *  exceeded its transmission quota the queue request can be rejected.
 *  The user should resubmit the request later when the queue has been
 *  depleted.
 *
 *  This implementation of ixAtmSchVcQueueUpdate uses no operating
 *  system or external facilities, either directly or indirectly.
 *  This allows clients to call this function form within an interrupt handler.
 *
 *  This interface is structurally compatible with the
 *  IxAtmdAccSchQueueUpdate callback type definition required for
 *  IXP400 ATM scheduler interoperability.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 *          updated is established.
 *
 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be updated.  This is the
 *          value returned by the @ref ixAtmSchVcModelSetup call which
 *          established the relevant VC.
 *
 * @param numberOfCells unsigned int [in] - Indicates how many ATM cells should
 *          be added to the queue for this VC.
 *
 * @return
 *  - <b>IX_SUCCESS :</b> The VC queue has been successfully updated.
 *  - <b>IX_ATMSCH_RET_QUEUE_FULL :</b> The VC queue has reached a
 *       preset limit.  This indicates the client has over-submitted
 *       and exceeded its transmission quota.  The request is
 *       rejected.  The VC queue is not updated.  The VC user is
 *       advised to resubmit the request later.
 *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is updated.
 *
 * @warning IxAtmSch assumes that the calling software ensures that
 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 *          ixAtmSchTableUpdate are both self and mutually exclusive
 *          for the same port.
 *
 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
PUBLIC IX_STATUS
ixAtmSchVcQueueUpdate( IxAtmLogicalPort port,
                       IxAtmSchedulerVcId vcId,
                       unsigned int numberOfCells);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchVcQueueClear( IxAtmLogicalPort port,
                      IxAtmSchedulerVcId vcId)
 *
 *  @brief The client calls this function to remove all currently
 *         queued cells from a registered VC.  The pending cell count
 *         for the specified VC is reset to zero.
 *
 *  This interface is structurally compatible with the
 *  IxAtmdAccSchQueueClear callback type definition required for
 *  IXP400 ATM scheduler interoperability.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port on which the VC to be
 *          cleared is established.
 *
 * @param vcId @ref IxAtmSchedulerVcId [in] - Identifies the VC to be cleared.  This is the
 *          value returned by the @ref ixAtmSchVcModelSetup call which
 *          established the relevant VC.
 *
 * @return
 *  - <b>IX_SUCCESS :</b> The VC queue has been successfully cleared.
 *  - <b>IX_FAIL :</b> The input are invalid.  No VC queue is modified.
 *
 * @warning IxAtmSch assumes that the calling software ensures that
 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 *          ixAtmSchTableUpdate are both self and mutually exclusive
 *          for the same port.
 *
 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
PUBLIC IX_STATUS
ixAtmSchVcQueueClear( IxAtmLogicalPort port,
                      IxAtmSchedulerVcId vcId);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchTableUpdate( IxAtmLogicalPort port,
                     unsigned int maxCells,
                     IxAtmScheduleTable **rettable)
 *
 *  @brief The client calls this function to request an update of the
 *         schedule table for a particular ATM port.
 *
 *  This is called when the client decides it needs a new sequence of
 *  cells to send (probably because the transmit queue is near to
 *  empty for this ATM port).  The scheduler will use its stored
 *  information on the cells submitted for transmit (i.e. data
 *  supplied via @ref ixAtmSchVcQueueUpdate function) with the traffic
 *  descriptor information of all established VCs on the ATM port to
 *  decide the sequence of cells to be sent and fill the schedule
 *  table for a period of time into the future.
 *
 *  IxAtmSch will guarantee a minimum of minCellsToSchedule if there
 *  is at least one cell ready to send. If there are no cells then
 *  IX_ATMSCH_RET_QUEUE_EMPTY is returned.
 *
 *  This implementation of ixAtmSchTableUpdate uses no operating
 *  system or external facilities, either directly or indirectly.
 *  This allows clients to call this function form within an FIQ
 *  interrupt handler.
 *
 * @param port @ref IxAtmLogicalPort [in] - Specifies the ATM port for which requested
 *          schedule table is to be generated.
 *
 * @param maxCells unsigned [in] - Specifies the maximum number of cells
 *          that must be scheduled in the supplied table during any
 *          call to the interface.
 *
 * @param **table @ref IxAtmScheduleTable [out] - A pointer to an area of
 *              storage is returned which contains the generated
 *              schedule table.  The client should not modify the
 *              contents of this table.
 *
 * @return
 *  - <b>IX_SUCCESS :</b> The schedule table has been published.
 *       Currently there is at least one VC queue that is nonempty.
 *  - <b>IX_ATMSCH_RET_QUEUE_EMPTY :</b> Currently all VC queues on
 *       this port are empty.  The schedule table returned is set to
 *       NULL.  The client is not expected to invoke this function
 *       again until more cells have been submitted on this port
 *       through the @ref ixAtmSchVcQueueUpdate function.
 *  - <b>IX_FAIL :</b> The input are invalid.  No action is taken.
 *
 * @warning IxAtmSch assumes that the calling software ensures that
 *          calls to ixAtmSchVcQueueUpdate, ixAtmSchVcQueueClear and
 *          ixAtmSchTableUpdate are both self and mutually exclusive
 *          for the same port.
 *
 * @warning Subsequent calls to this function for the same port will
 *          overwrite the contents of previously supplied schedule
 *          tables.  The client must be completely finished with the
 *          previously supplied schedule table before calling this
 *          function again for the same port.
 *
 * @sa ixAtmSchVcQueueUpdate(), ixAtmSchVcQueueClear(), ixAtmSchTableUpdate().  */
PUBLIC IX_STATUS
ixAtmSchTableUpdate( IxAtmLogicalPort port,
                     unsigned int maxCells,
                     IxAtmScheduleTable **rettable);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchShow(void)
 *
 *  @brief Utility function which will print statistics on the current
 *         and accumulated state of VCs and traffic in the ATM
 *         scheduler component.  Output is sent to the default output
 *         device.
 *
 * @param none
 * @return none
 */
PUBLIC void
ixAtmSchShow(void);

/**  
 * @ingroup IxAtmSch
 *
 * @fn ixAtmSchStatsClear(void)
 *
 *  @brief Utility function which will reset all counter statistics in
 *         the ATM scheduler to zero.
 *
 * @param none
 * @return none
 */
PUBLIC void
ixAtmSchStatsClear(void);

#endif
/* IXATMSCH_H */

/** @} */