Cisco IOS Programmer’s Guide/ Architecture Reference

The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated m a commercial environment. This equipment generates, uses, and can radiate radio-frequency energy and. if not installed and used in accordance with the instruction manual, may cause harmful mterference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be required to correct the interference at their own expense.The following information is for FCC compliance of Class В devices: The equipment described in this manual generates and may radiate radio-frequency energy. If it is not installed in accordance with Cisco’s installation instructions, it may cause interference with radio and ufevision reception. This equipment has been tested and found to comply with the limits for a Class В digital device in accordance with the specifications in part 15 of the FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation.Modifying the equipment without Cisco’s written authorization may result in the equipment no longer complying with FCC requirements for Class A or Class В digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be requkdto correct any interference to radio or television communications at your own expense.You can determine whether your equipment is causing mterference by turning it off. If the interference stops, it was probably caused by the Cisco equipment or one of its peripheral devices. If the equipment causes interference to radio or television reception, try to correct the interference by using one or more of the following measures:• Turn the television or radio antenna until the interference stops.• Move the equipment to one side or the other of the television or radio.• Move the equipment farther away from the television or radio.• Plug the equipment into an outlet that is on a different circuit from the television or radio. (That is, make certain the equpment and the television or radio are on circuits controlled by different circuit breakers or fuses.)Modifications to this product not authorized by Cisco Systems, Inc. could void the FCC approval and negate your authority to operate the product.The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California. Berkeley (UCB) as part of UCB4 public domain version of the UNIX operating system. All rights reserved. Copyrightc 1981. Regents of the University of California.

---

Table of contents :
Cisco IOS Programmer’s Guide/ Architecture Reference……Page 1
Changes in the Fifth Edition (February 1999)……Page 5
Changes in the Fourth Edition (December 1997)……Page 6
Changes in the Third Edition (September 1996)……Page 7
Changes in the Second Edition (February 1996)……Page 9
Figures……Page 37
Tables……Page 39
Document Organization……Page 43
Document Conventions……Page 45
Overview……Page 47
1.2.1 Subblock and Lists……Page 49
1.3.1 Scheduler……Page 50
1.3.3 Pools, Buffers, and Particles……Page 51
1.4 Kernel Support Services……Page 52
1.4.3 Timer Services and Time-of-Day Services……Page 53
1.5.1 Binary Trees……Page 54
1.7 Network Service and Protocols……Page 55
1.8.3 IF-MIB……Page 57
2.2.1 Initialization by the ROM Monitor……Page 59
2.2.2.2 Bootstrap a Cisco IOS Image from a Network……Page 60
2.2.3 Allow the Cisco IOS Image to Take Control of the Platform……Page 61
2.2.4 Fundamental Initialization……Page 62
2.3 Cisco IOS Initialization Process……Page 64
2.5.2 Health Monitoring……Page 65
2.5.3.3 Time……Page 66
2.5.3.6 Auto Sync……Page 67
2.5.4.1 Basic Slave Operation……Page 68
2.6 Implementation Guide……Page 69
2.6.1 Initializing EHSA……Page 70
2.6.2 EHSA APIs……Page 71
2.0.0.2 Using ehsa_event() to Trigger State Transitions……Page 72
2.0.1 Examples……Page 73
2.0.1.2 Determining Primary/Secondary Status……Page 74
2.0.3 The Primary Background Process……Page 75
2.0.4 Changes in the Initialization Sequence……Page 76
2.1 Common EHSA CLI……Page 77
2.1.2.3 Redundancy Operations……Page 78
2.2.1 Background……Page 79
2.2.2 What happens when a Primary crashes?……Page 80
2.2.4 Summary of Routines and Code Additions……Page 81
Kernel Services……Page 83
3.1.1 Important Coding Guidelines……Page 85
3.1.2 if_onesec Registry Removed……Page 86
3.1.4 API for Keepalive and Other Periodic Intervals……Page 87
3.1.4.1 New Implementation……Page 88
3.1.4.2 Setting the Periodic Interval……Page 89
3.2 Processes: Overview……Page 90
3.2.4 Process States……Page 91
3.3.1.1 Ready Queues……Page 92
3.3.2 Process Priorities……Page 93
3.3.3 Operation of Scheduler Queues……Page 94
3.4.2 Enqueue Data for a Process……Page 96
3.4.5 Set and Retrieve Information about a Process……Page 97
3.4.9 Suspend a Process……Page 98
3.4.10 Wake Up a Process……Page 99
3.5 Scheduler Objects: Overview……Page 100
3.6.5 Enqueue an Item onto a Watched Queue……Page 101
3.6.11 Delete a Watched Queue……Page 102
3.7.6 Register a Process for Notification on a Watched Boolean……Page 103
3.8.4 Lock and Unlock a Semaphore……Page 104
3.9.2 Create a Watched Bit Field……Page 105
3.9.8 Delete a Watched Bit Field……Page 106
3.11 Scheduler: Example Code……Page 107
Main Loop……Page 108
Exit Handler……Page 109
4.1.3 Chunk Manager……Page 111
4.2.1 Regions: Definition……Page 112
4.2.3 Region Hierarchies: Definition……Page 113
4.2.5 Set a Region’s Class……Page 114
4.2.6 Set Media Access Attributes……Page 115
4.2.7.1 Region Hierarchy Types……Page 116
4.2.8.1 Example: Establish an Alias Region……Page 117
4.2.10 Search through Memory Regions……Page 118
4.2.12 Determine a Region’s Size……Page 119
4.2.13 Retrieve a Region’s Attributes……Page 120
4.3.2 Free Lists: Overview……Page 121
4.3.5.1 Mandatory Memory Pool Classes……Page 122
4.3.6.1 Example: Alias Memory Pools……Page 123
4.3.8.2 Allocate Aligned Memory……Page 124
4.3.8.4 Guidelines for Allocating Memory……Page 125
4.3.10.1 Example: Lock Memory……Page 127
4.3.11 Add Free List Sizes……Page 128
4.3.12.3 Determine Whether Memory Is Low……Page 129
4.4.1 Overview: Chunk Manager……Page 130
4.4.3 Create a Memory Chunk……Page 131
4.4.5 Lock a Memory Chunk……Page 132
4.5.1 Determine Amount of Memory Available……Page 133
4.6.1 Introduction to VM……Page 134
4.6.2 Overview of Cisco IOS VM……Page 135
4.6.3 Engineering Effort……Page 136
4.6.4 VM Rules……Page 137
4.6.5.2 What is an “address interval”?……Page 138
4.6.6 Porting VM to a Platform……Page 139
4.6.7 Wish List……Page 140
4.6.8 Style Considerations……Page 141
4.6.9 Basic VM Terms and Concepts……Page 142
5.2 Generic Pool Management……Page 147
5.2.4 Permanent and Temporary Items: Definition……Page 148
5.2.5 Create a Pool……Page 149
5.3.2 Structure of a Pool with a Cache……Page 150
5.3.3 Add a Pool Cache……Page 151
5.4.2 Buffer Data Blocks……Page 152
5.4.2.1 Memory Organization within a Data Block……Page 153
5.5.4 Create a Private Buffer Pool……Page 154
5.5.6 Obtain a Buffer from a Private Buffer Pool……Page 155
5.5.9.1 Overview: Duplicate a Buffer……Page 156
5.5.9.3 Duplicate a Buffer and Its Context……Page 157
5.5.9.5 Comparison of Buffer Duplication with and without Recentering……Page 158
5.6.1.1 Example: Create and Fill a Buffer Cache……Page 159
5.7.3 Remove a Buffer from the Input Queue of an Interface……Page 160
5.8.2 Particle Structure……Page 161
5.9.2 Create a Particle Cache……Page 162
5.9.7 Coalesce Buffers Containing Particles……Page 163
6.2.2 Proliferation of Application Variables……Page 165
6.3.1 Subblocks and Private Lists……Page 166
6.3.2 Maximum Interfaces Constant No Longer a Global Value……Page 167
6.3.3.2 Creating Interface Names……Page 168
6.3.3.3 Parsing the IDB Naming and Numbering System……Page 169
6.3.3.8 Testing……Page 170
6.4.2 IDB Subblock……Page 171
6.6 Types of Subblocks……Page 172
6.7.1 Example: Creating a Subblock……Page 173
6.7.3 Common Subblock Header……Page 174
6.8.1 Implementation Details……Page 175
6.8.2.2 Migrating Data from IDB to Subblock……Page 177
6.9.1 Create an IDB……Page 178
6.10.1 Subblocks Types……Page 180
6.10.4 Return a Pointer to an IDB Subblock……Page 181
6.10.7 Release an IDB Subblock……Page 182
6.11.1 Create a Private List of IDBs……Page 183
6.12.1 Apply a Function over a Private IDB List……Page 184
6.14 Enqueue, Dequeue, and Transmit a Packet……Page 185
7.1 Platform-Specific Initialization: Overview……Page 187
7.3 Memory Initialization……Page 188
7.3.1 Example: Memory Initialization……Page 189
7.5 Interface and Line Initialization……Page 190
7.5.1 Example: Interface Initialization……Page 191
7.6 Platform-Specific Strings……Page 193
7.6.1 Examples: Platform-Specific Strings……Page 194
7.7 Platform-Specific Values……Page 195
7.7.1 Examples: Platform-Specific Values……Page 197
8.1 Overview: IPC Services……Page 199
8.3 IPC Communication: Overview……Page 200
8.4.4 Port Identifier: Definition……Page 201
8.5 Port Naming Services……Page 202
8.5.2.2 Reserved Port Names……Page 203
8.6 IPC Message Format……Page 204
8.8.1 Seat Table: Description……Page 205
8.9.1 Port Table: Description……Page 206
8.9.4 Open a Port……Page 207
8.9.7 Remove a Port……Page 208
8.11.2 Send a Message……Page 209
8.13 Write an IPC Application……Page 210
8.13.3.1 Send a Message in Blocking Mode……Page 211
8.14 Implementing IPCs on the RSP Platform……Page 212
8.14.2.1 Discovery Phase……Page 213
8.14.2.2 Initialization Phase……Page 214
8.14.3 Invoke the IPC Setup Procedure……Page 215
8.14.6 IPC Name Service……Page 216
9.1.1 Application Level API……Page 219
9.1.4 File System Features……Page 220
9.3.1.1 Defining a File System……Page 221
9.3.1.2 Defining a File……Page 222
9.3.1.3 Example 1 – Reading a File……Page 223
9.3.1.5 Example 3 – Writing a File……Page 225
9.3.2.1 Directories……Page 229
9.4.1 IFS/File System API……Page 230
9.4.2 Common Data Structures……Page 232
9.4.3 Implementation……Page 233
9.5.2 Copy Behavior Hook……Page 235
9.6 References……Page 236
Socket Interface……Page 237
ANSI C Library……Page 239
Kernel Support Services……Page 241
12.1.2 How to Choose a Subsystem Class……Page 243
12.2.2 Sequencing Property……Page 244
12.3 Define a Subsystem……Page 245
12.3.1 Examples: Define a Subsystem……Page 246
12.5.1 Create a New Subsystem……Page 247
12.5.4 Use New IDB Subblocks to Store Private Variables……Page 250
13.2 Registry Compiler: Description……Page 251
13.4.1 11.3 Changes……Page 252
13.5 .reg File Metalanguage……Page 253
13.5.1 Example: .reg File Format……Page 255
13.6 .h File Contents……Page 256
13.8 Placement of xxx_registry.o in makefiles……Page 257
13.11 ‘show registry’ Support……Page 258
13.12.1.1 Example: Define a List Service……Page 259
13.13.1 Define a Pid_list Service……Page 260
13.13.1.2 Example: Add To a Pid_list Service……Page 261
13.14.1 Define a Case Service……Page 262
13.14.1.3 Example: Add a Default Case Function……Page 263
13.16.1 Define a Loop Service……Page 264
13.16.1.2 Example: Add To a Loop Service……Page 265
13.17.1 Define a Stub Service……Page 266
13.18 Manipulate Value Services……Page 267
13.18.1.2 Example: Add To a Value Service……Page 268
13.18.1.4 Example: Invoke a Value Service……Page 269
14.1.2.1 clock_epoch Structure……Page 271
14.1.4 Time Zones……Page 272
14.2 Get the Current Time……Page 273
14.6 Determine Validity of System Clock Time……Page 274
14.7 Format Time Strings……Page 276
15.1.1 System Clock……Page 277
15.3 Passive Timers……Page 278
15.3.1.3 Set the Expiration for a Passive Timer……Page 279
15.3.1.6 Guidelines for Using the SLEEPING and AWAKE Macros in Releases Prior to Release11.1……Page 280
15.3.1.11 Update Passive Timers in the Future……Page 281
snark_block……Page 282
15.3.2.3 Determine the Elapsed Time……Page 283
15.3.3 Compare Timestamps……Page 284
15.4.4 Operation of Managed Timers……Page 285
15.4.7 Initialize Managed Timers……Page 286
15.4.11 Start a Leaf Timer……Page 287
15.4.14 Stop a Managed Timer……Page 288
15.4.16.2 Set Extended Context……Page 289
15.4.16.5 Traverse a Tree of Managed Timers……Page 290
15.4.17 Example: Managed Timers……Page 291
15.6 Determine System Uptime……Page 293
16.1.3 Print a String into a Buffer……Page 295
16.1.4.1 Examples: Format Time Strings……Page 296
16.1.5.1 Examples: Format Timestamps……Page 297
16.1.6.1 %a Format Code……Page 298
16.1.6.2 %A Format Code……Page 299
16.1.7.1 %z Format Code……Page 301
16.1.7.2 %Z Format Code……Page 302
17.2 List of Exceptions……Page 303
17.3.1.1 Example: Register a One-Time Handler……Page 304
17.4 Cause Exceptions……Page 305
17.4.1 Example: Cause Exceptions……Page 306
18.1.1 Use Core Files to Debug CPU Exceptions……Page 307
18.1.1.1 Configure the Cisco IOS Software to Generate a Core File……Page 308
18.1.2 Debug with the ROM Monitor……Page 309
18.1.3.2 Debug in GDB Process Mode……Page 310
18.3 Debug Using Compile-Time Conditionals……Page 311
18.3.1.1 Example: Trace Buffer Leaks……Page 312
Network Services……Page 315
19.1 Overview: Binary Trees……Page 317
19.2.1 Initialize an RB Tree……Page 318
19.2.5 Retrieve Information about an RB Tree……Page 319
19.3 AVL Trees……Page 320
19.3.1.2 Insert a Node into an AVL Tree……Page 321
19.3.2.1 Initialize a Wrapped AVL Tree……Page 322
19.3.2.5 Remove a Node from a WAVL Tree……Page 323
19.4.3 Traverse a Radix Tree……Page 324
19.4.6 Delete a Node from a Radix Tree……Page 325
20.1.1 Singly Linked Lists (Queues)……Page 327
20.2.1 Initialize a Queue……Page 328
20.3.1.1 Add an Item to a Queue……Page 329
Example 2……Page 330
20.3.2.3 Example: Manipulate Protected Direct Queues……Page 331
20.4.4 Remove an Item from a Queue……Page 332
Example 2……Page 333
20.5.3 Example: Manipulate Doubly Linked Lists……Page 334
20.6.4 Add an Item to a List……Page 335
20.6.7 Change the Behavior of List Action Vectors……Page 336
Example 1……Page 337
Example 2……Page 338
Example 3……Page 339
21.1.1 Slow Switching……Page 341
21.2.1.1 MCI/CiscoBus Architecture……Page 342
Receive a Packet……Page 343
Transmit a Packet: Intracard……Page 344
Transmit a Packet: Intercard……Page 346
Receive a Packet……Page 348
Transmit a Packet……Page 349
21.2.2.1 Full Matrix……Page 350
21.2.2.2 Unique Routines……Page 351
Hardware-Specific Design……Page 353
22.1 Portability Issues……Page 355
22.1.1.1 Unions……Page 356
22.1.1.2 Bit Fields……Page 357
22.1.2 Data Alignment……Page 358
22.1.5.1 Performance……Page 359
22.1.5.3 Compliance with Encapsulations……Page 360
22.2.1 Inline Assembler……Page 361
22.2.4 Endian #defines……Page 362
22.2.6 Canonical Functions……Page 363
Management Services……Page 365
23.1.1 Traversing the Parse Tree……Page 367
23.1.2 Transition Structure……Page 368
23.2.1.1 Example: Construction of Parse Trees……Page 369
23.2.2 Parse a Keyword Token……Page 370
23.2.2.1 Example: Parse a Keyword Token……Page 371
23.2.3 Parse a Number Token……Page 372
23.2.3.1 Example: Parse a Number Token……Page 373
23.2.5 Parse Optional Keywords……Page 374
23.2.6 Parse Mixed String and Nonstring Tokens……Page 375
23.2.7 Process “No” Commands……Page 376
23.2.7.2 Example: Process “No” Commands……Page 377
23.3.1 Example: Link Parse Trees……Page 378
23.4.1 Overview: CSB Objects……Page 379
23.5.1.1 Example: Create a Link Point……Page 381
23.5.4.1 Example: Link Commands to a Link Point……Page 382
23.5.5.1 Example: Create Link Exit Points……Page 383
23.6.2.1 Example: Add an Alias to a Mode……Page 384
24.1 SNMP Overview……Page 385
24.1.4 SMI: Definition……Page 386
24.2.1 MIB: Overview……Page 387
24.2.5.1 Object: Definition……Page 388
24.2.5.3 Object Identifier: Definition……Page 389
24.2.6.2 Simple SNMP Conceptual Tables……Page 390
24.2.6.5 Tables Inside of Tables……Page 391
24.3.1 Primitive Data and Application Types……Page 392
24.3.2 Textual Conventions……Page 393
24.5.1 MIB Design: Overview……Page 394
24.5.3 MIB Design Phases……Page 395
24.5.3.2 Design the Notifications……Page 396
24.5.4 Check for Existing MIB Implementations……Page 397
24.5.6.1 Assigned Numbers……Page 398
Cisco MIB Nomenclature……Page 399
Cisco MIB Template……Page 400
Example: MIB in Cisco Template……Page 401
Objects in NVRAM……Page 403
24.5.7.3 Invoke the MIB Compiler……Page 404
24.7 Establish a New MIB……Page 405
24.8 Compile a MIB……Page 408
24.8.4 Makefile Rules for Compiling MIBs……Page 409
24.8.5 Invoke the MIB Compiler……Page 410
24.8.7 Output from the MIB Compiler……Page 411
Compile MIB-II……Page 412
24.9.2 Instrumentation……Page 413
24.10.2 Validation……Page 414
24.11 Implement SNMP Asynchronous Notifications……Page 415
24.11.3 Control the Notification……Page 416
24.11.4 Generate the Notification……Page 419
24.12 Test a MIB……Page 420
24.12.3.1 Command-Line Tools……Page 421
24.12.3.3 Notification Tools……Page 422
24.13.1 Release MIB Code……Page 423
24.14.1 Use MIB Versions……Page 424
24.16 Create or Update a MIB Workspace……Page 426
24.17 Test a MIB……Page 427
24.19 Determine Whether You Have an SNMPv1 or SNMPv2 MIB……Page 428
24.21.1 Use Make Directly to Generate an SNMPv2 MIB……Page 429
24.22.1 Prerequisites for Publishing a MIB……Page 430
24.23.3 Files in the MIB Repository and Workspace……Page 431
24.23.4 Directory Layout for MIB Repository and Workspace……Page 432
25.1.2 API……Page 435
25.2.1 Adding to Service Points……Page 436
25.2.3 Deregistering a Sublayer……Page 438
25.3.1 Adding Service Points: Frame Relay……Page 439
25.4 Link Up/Down Trap Support……Page 440
Other Useful Information……Page 441
26.2 The Typical Scenario……Page 443
26.2.1.1 CPU Utilization……Page 444
26.3 Addressing the Problems……Page 445
26.3.1 Process Structure……Page 446
26.3.2 Stability through Rate Control……Page 447
26.3.3 Avoiding Receive Buffer Starvation……Page 448
26.3.5 Complexity versus Efficiency……Page 449
26.4 Conclusion……Page 450
27.1.1 Operation……Page 451
27.1.4 Specifying Backup Delays……Page 452
27.1.6 Notes On Operation……Page 453
Solution……Page 454
Solution……Page 455
Solution……Page 456
28.2 Why Create Modular Images?……Page 457
28.5.1 Build All Modular Images for a Single Platform……Page 458
28.6 Build Modular Images for All Platforms……Page 459
28.8 Modularity Checking Done by the Nightly Builds……Page 460
29.2 How Customers See Release-Note Enclosures……Page 461
29.5.2 Writing Guidelines……Page 462
29.5.3 Writing Style……Page 463
Examples: Character Formatting Guidelines……Page 465
29.5.6 Sample Release-Note Enclosures……Page 466
29.6 Writing DDTS Headlines……Page 467
29.7 Getting Help……Page 469
A.1.1 Coding Conventions: Something for Everyone to Protest……Page 473
A.2 Design Issues……Page 474
A.2.2 Plan Your Feature as a Subsystem……Page 475
A.2.5 Don’t Hog the Chip……Page 476
A.3.1 Use ANSI C……Page 477
Typecasting……Page 478
Enumerated Types and #defines……Page 479
Header Files……Page 480
Spaces in Function Definitions and Prototypes……Page 481
Formatting Block Comments……Page 482
A.5 Variable and Storage Persistence, Scope, and Naming……Page 483
Checking the malloc() and getbuffer Return……Page 484
A.7 Coding for Performance……Page 485
A.7.1 Performance of Algorithms and Data Structures……Page 486
A.7.3.1 Helping GCC Turn Glop into Gold……Page 487
A.7.3.2 Not All Memories Are Golden……Page 489
B.1 Description of the Cisco IOS Subsystems……Page 491
B.2.1 IP Host Subsystem……Page 501
B.2.2 IP Routing Subsystem……Page 504
B.3.1 Scheduler Subsystem……Page 505
B.3.4 Parser Subsystem……Page 506
B.3.6 Core Router Subsystem……Page 507
B.3.8 Core Time Services and Timer Subsystem……Page 508
B.3.10 Miscellaneous Subsystems……Page 509
C.2.2 Profile Block Bins……Page 511
C.3 Caveats about Using CPU Profiling……Page 512
C.5.1 Create a Profile Block and Enable Profiling……Page 513
C.5.7 Disable Task and Interrupt Modes……Page 514
C.6 Process the Profiler Output……Page 515
D.2.1 Scheduler Queues……Page 517
D.2.2 Operation of Scheduler Queues……Page 518
D.2.2.1 Overall Scheduler Queue Operation……Page 519
Check the Compatibility Queues……Page 520
Check the Compatibility Queues……Page 522
Classification……Page 524
Related Functions……Page 525
Related Functions……Page 526
Classification……Page 527
Input Parameters……Page 528
Return Values……Page 529
Related Function……Page 530
Glossary……Page 531
Index……Page 545