stktask.h (18719B)
1 /* 2 * 3 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 4 * 5 * Copyright 2007-2019 Broadcom Inc. All rights reserved. 6 * 7 * File: stktask.h 8 * Requires: Definition of disc_pkt_type_get to get type of a disc pkt 9 * DISC packet type definitions 10 * CPUDB module 11 */ 12 13 #ifndef _STKTASK_H_ 14 #define _STKTASK_H_ 15 16 #include <sdk_config.h> 17 #include <sal/core/thread.h> 18 #include <sal/core/time.h> 19 20 #include <bcm/types.h> 21 22 #include <appl/cpudb/cpudb.h> 23 24 #include <shared/evlog.h> /* Event Logging */ 25 26 #include <appl/discover/disc.h> /* disc_election_cb_t */ 27 28 /* See requirements above */ 29 30 /**************************************************************** 31 * 32 * Stack task states and events 33 * 34 * 35 * The normal transitions are: 36 * 37 * BLOCKED ------> READY --------> DISC 38 * ^ | 39 * | V 40 * +----------- ATTACH <------- TOPO 41 * 42 * From -> To Reason 43 * 44 * BLOCKED -> READY Unblock event or blocked timeout 45 * READY -> DISC Various events start discovery 46 * DISC -> TOPO DISC_SUCCESS 47 * TOPO -> ATTACH TOPO_SUCCESS 48 * ATTACH -> BLOCKED ATTACH_SUCCESS 49 * 50 * The application may provide a callback function which will be called 51 * on all state transitions. 52 */ 53 54 typedef enum bcm_st_state_e { 55 BCM_STS_INVALID = 0, 56 57 BCM_STS_BLOCKED, /* Record events and wait for unblock */ 58 BCM_STS_READY, /* Ready to start discovery */ 59 BCM_STS_DISC, /* Discovery is running */ 60 BCM_STS_TOPO, /* Topology processing is running */ 61 BCM_STS_ATTACH, /* Attach callbacks are running */ 62 63 BCM_STS_MAX 64 } bcm_st_state_t; 65 66 #define BCM_ST_STATE_STRINGS { \ 67 "INVALID", \ 68 "BLOCKED", \ 69 "READY", \ 70 "DISC", \ 71 "TOPO", \ 72 "ATTACH", \ 73 "" } 74 75 /* 76 * These are the default timeout settings, per state. Note that discovery 77 * has its own timeout mechanism as well. In addition, st_cfg_flags 78 * supports an automatic transition from blocked to ready. 79 */ 80 81 #ifndef BCM_STATE_TIMEOUT_DEFAULTS 82 #define BCM_STATE_TIMEOUT_DEFAULTS { \ 83 0, /* BCM_STS_INVALID */ \ 84 0, /* BCM_STS_BLOCKED */ \ 85 0, /* BCM_STS_READY */ \ 86 0, /* BCM_STS_DISC */ \ 87 10 * ATP_TIMEOUT_DEFAULT, /* BCM_STS_TOPO */ \ 88 15 * ATP_TIMEOUT_DEFAULT /* BCM_STS_ATTACH */ \ 89 } 90 #endif 91 92 93 extern char * bcm_st_state_strings[]; 94 95 #define BCM_STS_VALID(state) ((state) > BCM_STS_INVALID && (state) < BCM_STS_MAX) 96 97 98 /**************************************************************** 99 * 100 * Event precedence: 101 * 102 * NOTE: The order of these flags determines the order in which 103 * they are processed when multiple events are pending. 104 * 105 * 106 * Events trigger transitions from one state to another. The order of 107 * events in this list is important because it determines the order in 108 * which they are evaluated. This affects the precedence of the events. 109 * For example, UNBLOCK is first so that if UNBLOCK and BLOCK events are 110 * seen together, the BLOCK event will be processed second, leaving Stack 111 * Task in the BLOCKED state. 112 * 113 * On the other hand, SUCCESS is given precedence over FAILURE in 114 * general by appearing first (Stack Task will transition due to the 115 * success signal first and then the failure will be discarded.) 116 * 117 * 118 * Below, "internal" means the event is generated by Stack Task; 119 * "external" means the event may be expected to be generated by the 120 * application via bcm_st_event_send. Some events may be both. 121 * 122 * UNBLOCK (external) 123 * Transition from BLOCKED to READY. This is sent by the 124 * application to indicate it is ready to participate in 125 * discovery. 126 * 127 * BLOCK (external) 128 * Transition to the BLOCKED state from any other state. This is 129 * sent by the application and generally indicates an error 130 * state. It will terminate a running discovery and prevent 131 * discovery from re-running until an UNBLOCK or TIMEOUT is 132 * received. 133 * 134 * LINK_UP, LINK_DOWN (internal, external) 135 * Stack Task registers with linkscan to receive link events. 136 * When that callback is made for a stack port, this event 137 * occurs. 138 * 139 * DISC_PKT (internal, external) 140 * A discovery packet was received by Stack Task indicating some 141 * other box may be trying to start discovery. 142 * 143 * DISC_SUCCESS, DISC_FAILURE (internal) 144 * These are sent upon the completion of discovery. 145 * 146 * DISC_RESTART (internal, external) 147 * Indicates discovery should be restarted. 148 * 149 * TOPO_SUCCESS, TOPO_FAILURE (external) 150 * Results of topology processing. 151 * 152 * ATTACH_SUCCESS, ATTACH_FAILURE (external) 153 * Results of device attach processing. 154 * 155 * TIMEOUT (internal) 156 * A timeout has occurred for a phase. Generally go to BLOCKED. 157 * 158 * COMM_FAILURE (internal, external) 159 * A communications failure has occurred. This usually results 160 * in a restart of discovery. 161 */ 162 163 typedef enum bcm_st_event_e { 164 BCM_STE_INVALID = 0, 165 166 BCM_STE_UNBLOCK, /* Move from BLOCKED to IDLE */ 167 BCM_STE_BLOCK, /* Move to BLOCKED from any state */ 168 BCM_STE_LINK_UP, 169 BCM_STE_LINK_DOWN, 170 BCM_STE_DISC_PKT, /* A discovery pkt seen from a stk port */ 171 BCM_STE_DISC_RESTART, /* Restart discovery if running */ 172 BCM_STE_DISC_SUCCESS, 173 BCM_STE_DISC_FAILURE, 174 BCM_STE_TOPO_SUCCESS, 175 BCM_STE_TOPO_FAILURE, 176 BCM_STE_ATTACH_SUCCESS, 177 BCM_STE_ATTACH_FAILURE, 178 BCM_STE_TIMEOUT, 179 BCM_STE_COMM_FAILURE, /* Communication failure seen */ 180 181 BCM_STE_MAX 182 } bcm_st_event_t; 183 184 #define BCM_ST_EVENT_STRINGS { \ 185 "INVALID", \ 186 "UNBLOCK", \ 187 "BLOCK", \ 188 "LINK_UP", \ 189 "LINK_DOWN", \ 190 "DISC_PKT", \ 191 "DISC_RESTART", \ 192 "DISC_SUCCESS", \ 193 "DISC_FAILURE", \ 194 "TOPO_SUCCESS", \ 195 "TOPO_FAILURE", \ 196 "ATTACH_SUCCESS", \ 197 "ATTACH_FAILURE", \ 198 "TIMEOUT", \ 199 "COMM_FAILURE", \ 200 "" } 201 202 extern char * bcm_st_event_strings[]; 203 204 #define BCM_STE_VALID(event) ((event) > BCM_STE_INVALID && (event) < BCM_STE_MAX) 205 206 #define BCM_STE_FLAG(event) (1 << (event)) 207 208 extern cpudb_ref_t volatile bcm_st_cur_db; 209 extern cpudb_ref_t volatile bcm_st_disc_db; 210 211 /**************************************************************** 212 * 213 * Configuration function prototypes 214 * and the configuration structure. 215 * 216 * 217 * int (*bcm_st_disc_f)(cpudb_ref_t db_ref, bcm_st_master_f done_cb); 218 * 219 * The one-shot discovery function. db_ref must be initialized with 220 * the local information. By some mechanism, it discovers the system 221 * members and interconnections, filling out db_ref. Once completed, 222 * it calls the master election done_cb (see below). 223 * 224 * Returns BCM_E_NONE on success. 225 * 226 * Returns DISC_RESTART_NEW_SEQ to request the caller change the 227 * discovery sequence number and call again. 228 * 229 * Returns DISC_RESTART_REQUEST to request the caller restart 230 * discovery (without changing the discovery sequence number). 231 * 232 * int (*bcm_st_master_f)(cpudb_ref_t db_ref); 233 * 234 * Takes a completed CPUDB and determines the master entry. It sets 235 * db_ref->master_entry to this value if found and returns 236 * BCM_E_NONE. 237 * 238 * int (*bcm_st_disc_abort_f)(int disc_rv, int timeout_us); 239 * 240 * The caller (Stack Task) uses this to interrupt a running 241 * discovery. It may intend to abort it or just to restart it. This 242 * difference is reflected in the disc_rv that is passed which is 243 * used by discovery when it exits. 244 * 245 * If timeout_us > 0, the call will block until discovery 246 * acknowledges that it has exited (returns BCM_E_NONE), or until the 247 * timeout is reached (returns BCM_E_FAIL). 248 * 249 * int (*bcm_st_transition_f)(st_state_t from, 250 * st_event_t event, 251 * st_state_t to, 252 * cpudb_ref_t disc_db, 253 * cpudb_ref_t cur_db); 254 * 255 * 256 * If present, Stack Task calls this each time a state transition 257 * takes place. Events sent to Stack Task from this callback will be 258 * processed after the transition has occurred. 259 * 260 * The disc_db and cur_db are pointers to the discovery and current 261 * database pointers. In general, they should be treated as 262 * "read-only". Either or both may be NULL; note that the case of 263 * "no previous successful discovery" can be detected by testing 264 * (cur_db == NULL). 265 * 266 * If the transition function returns an error (< 0) then ST will 267 * transition to BLOCKED (without an additional callback). 268 * 269 * st_topo and st_attach: int (*bcm_st_update_f)(cpudb_ref_t db_ref); 270 * 271 * These are called at the transitions to the TOPO and ATTACH states, 272 * respectively. For st_topo, the discovery data base is passed as 273 * the parameter. For st_attach, the new current database is passed 274 * as the parameter. 275 * 276 * The values for these functions in the Broadcom distribution are 277 * bcm_stack_topo_update and bcm_stack_attach_update. 278 * 279 * The return values for these functions are only used to generate 280 * warning messages if they fail. The application must send a BLOCK 281 * event if it wishes to change the state of Stack Task. 282 */ 283 284 typedef disc_start_election_cb_t bcm_st_master_f; 285 286 typedef int (*bcm_st_disc_f)(cpudb_ref_t db_ref, 287 bcm_st_master_f done_cb); 288 typedef int (*bcm_st_disc_abort_f)(int disc_rv, int timeout_us); 289 typedef int (*bcm_st_transition_f)(bcm_st_state_t from, 290 bcm_st_event_t event, 291 bcm_st_state_t to, 292 cpudb_ref_t disc_db, 293 cpudb_ref_t cur_db); 294 295 typedef int (*bcm_st_update_f)(cpudb_ref_t db_ref); 296 297 typedef struct bcm_st_config_s { 298 bcm_st_disc_f st_disc_start; /* Start discovery */ 299 bcm_st_disc_abort_f st_disc_abort; /* Abort or restart discovery */ 300 bcm_st_master_f st_master; /* election functions */ 301 302 bcm_st_update_f st_topo; /* Start topo processing */ 303 bcm_st_update_f st_attach; /* Start attach processing */ 304 305 bcm_st_transition_f st_transition; /* All transitions */ 306 307 cpudb_base_t base; /* Local system info */ 308 } bcm_st_config_t; 309 310 /**************************************************************** 311 * 312 * API functions 313 * 314 * config_load may be called before start to set up the 315 * configuration; then ports may be deactivated before starting. 316 * 317 * Start/stop stack task 318 * 319 * Update the base configuration for the system 320 * 321 * Change/check timeouts associated with each state. 322 * A timeout may be assigned to each state. All states will 323 * transition to BLOCKED if a timeout occurs except for BLOCKED 324 * which will transition to READY. A timeout of 0 means disabled. 325 * Default timeouts are all 0 (disabled). 326 */ 327 328 extern int bcm_st_config_load(bcm_st_config_t *config); 329 330 extern int bcm_st_start(bcm_st_config_t *config, int enable); 331 extern int bcm_st_stop(int timeout_us); 332 333 extern int bcm_st_base_update(cpudb_base_t *base, int restart); 334 335 extern int bcm_st_event_send(bcm_st_event_t event); 336 337 extern int bcm_st_timeout_set(bcm_st_state_t state, sal_usecs_t to); 338 extern int bcm_st_timeout_get(bcm_st_state_t state, sal_usecs_t *to); 339 340 /* See notes below about bcm_st_cfg_flags */ 341 extern int bcm_st_link_state_set(int unit, bcm_port_t port, int link); 342 extern int bcm_st_link_state_get(int unit, bcm_port_t port, int *link); 343 344 /**************************************************************** 345 * 346 * These determine which events allow a transition from 347 * READY -> DISC 348 * 349 * DISC_RESTART is treated specially in some places in the code. 350 * It is really a "hard" restart and forces a transition to DISC 351 * from TOPO or ATTACH states as well. 352 */ 353 354 extern uint32 bcm_st_disc_startable_events; 355 #define BCM_ST_DISC_STARTABLE_EVENTS_DEFAULT ( \ 356 BCM_STE_FLAG(BCM_STE_LINK_UP) | \ 357 BCM_STE_FLAG(BCM_STE_LINK_DOWN) | \ 358 BCM_STE_FLAG(BCM_STE_DISC_PKT) | \ 359 BCM_STE_FLAG(BCM_STE_DISC_RESTART) | \ 360 BCM_STE_FLAG(BCM_STE_COMM_FAILURE)) 361 362 /* These are events that may start discovery directly */ 363 #define BCM_STE_DISC_STARTABLE(event) \ 364 ((BCM_STE_FLAG(event) & bcm_st_disc_startable_events) != 0) 365 366 #ifndef BCM_ST_DISC_PRIORITY_DEFAULT 367 #define BCM_ST_DISC_PRIORITY_DEFAULT 100 368 #endif 369 #ifndef BCM_ST_LSCAN_PRIORITY_DEFAULT 370 #define BCM_ST_LSCAN_PRIORITY_DEFAULT 50 371 #endif 372 #ifndef BCM_ST_DISC_STACK_SIZE_DEFAULT 373 #define BCM_ST_DISC_STACK_SIZE_DEFAULT SAL_THREAD_STKSZ 374 #endif 375 376 extern int bcm_st_disc_priority; 377 extern int bcm_st_disc_stk_size; 378 379 /* 380 * If an unexpected event occurs, a warning is produced. This can 381 * be set to 0 to squelch warnings. 382 */ 383 384 #ifndef BCM_ST_MAX_BAD_EVENT_WARNINGS_DEFAULT 385 #define BCM_ST_MAX_BAD_EVENT_WARNINGS_DEFAULT 10 386 #endif 387 extern int bcm_st_max_bad_event_warnings; 388 389 /**************************************************************** 390 * 391 * If discovery is stopped, wait for the stack task discovery thread 392 * to sleep. This is the max number of retries, with 10000 usecs of 393 * sleep between each. 394 */ 395 396 #define BCM_ST_DISC_STOP_RETRIES_MAX 1000 397 398 /**************************************************************** 399 * 400 * Stack Task state flags. These are only exposed for debugging. 401 */ 402 403 #define BCM_STF_CONFIG_LOADED 0x1 404 #define BCM_STF_RUNNING 0x2 405 #define BCM_STF_ABORT 0x4 406 #define BCM_STF_DISC_SLEEPING 0x8 407 #define BCM_STF_MAX 4 408 409 #define BCM_ST_FLAGS_STRINGS { \ 410 "CONFIG LOADED", \ 411 "RUNNING", \ 412 "ABORT", \ 413 "DISC SLEEPING", \ 414 "" } 415 416 extern char * bcm_st_flags_strings[]; 417 418 /**************************************************************** 419 * 420 * Stack Task configuration parameters 421 */ 422 423 /* 424 * bcm_st_cfg_flags: Configuration flags for stack task. 425 * 426 * BCM_STC_AUTO_B2R: Indicates stack task should automatically transition 427 * from blocked to ready. This may change dynamically. 428 * 429 * BCM_STC_INITIAL_LINK_UP: When the stack port links are initially 430 * checked, should a link up event be sent to stack task if any 431 * links are found? 432 * 433 * Applications may control link and communication failure signalling 434 * to stack task by clearing the following bits and setting up 435 * their own routines to send signals. NOTE, however, that link 436 * status maintains a lot of state and does its own debounce. If 437 * the application sends link signals, it must call st_link_state_set 438 * as well. Debounce is then disabled. 439 * 440 * BCM_STC_LINK_REGISTER: Use the default link change callback 441 * handler. 442 * 443 * BCM_STC_COMM_FAIL_REGISTER: Use the default communication 444 * failure callback handler, registering with ATP. 445 * 446 * BCM_STC_INITIAL_LINK_UP: When the stack port links are initially 447 * checked, should a link up event be sent to stack task if any 448 * links are found? 449 * 450 * BCM_STC_DISC_PKT_REGISTER: Register to get next hop pkts, check them 451 * and send disc_pkt events to stack task. 452 * 453 * BCM_STC_START_ATP: Should stack task check and start ATP if it's not 454 * running? 455 * 456 * bcm_st_link_up_db_usec: Number of microseconds that a stack port 457 * must remain up before an actual link up event is given. Link down 458 * is always payed attention to immediately (if current state is up). 459 * 460 * Stack ports may be enabled/disabled by calling bcm_st_stk_port_enable_set. 461 * The configuration must already be initialized or else the port 462 * won't be found. 463 */ 464 465 extern volatile uint32 bcm_st_cfg_flags; 466 467 #define BCM_STC_AUTO_B2R 0x1 468 #define BCM_STC_INITIAL_LINK_UP 0x2 469 #define BCM_STC_LINK_REGISTER 0x4 470 #define BCM_STC_COMM_FAIL_REGISTER 0x8 471 #define BCM_STC_DISC_PKT_REGISTER 0x10 472 #define BCM_STC_START_ATP 0x20 473 474 475 #define BCM_ST_CFG_FLAGS_STRINGS { \ 476 "AUTO B2R", \ 477 "INITIAL LINK UP", \ 478 "LINK REGISTER", \ 479 "COMM FAIL REGISTER", \ 480 "DISC PKT REGISTER", \ 481 "START ATP", \ 482 "" } 483 484 #define BCM_ST_CFG_FLAGS_DEFAULT ( \ 485 BCM_STC_AUTO_B2R | \ 486 BCM_STC_INITIAL_LINK_UP | \ 487 BCM_STC_LINK_REGISTER | \ 488 BCM_STC_COMM_FAIL_REGISTER | \ 489 BCM_STC_DISC_PKT_REGISTER | \ 490 BCM_STC_START_ATP \ 491 ) 492 493 extern volatile int bcm_st_link_up_db_usec; 494 #ifndef BCM_ST_LINK_UP_DB_USEC_DEFAULT 495 #define BCM_ST_LINK_UP_DB_USEC_DEFAULT 1000000 496 #endif 497 498 extern int bcm_st_stk_port_enable_set(int unit, int port, int enable); 499 extern int bcm_st_stk_port_enable_get(int unit, int port, int *enable); 500 501 /* For stack port flags */ 502 #define ST_SPF_LINK_UP 0x1 503 #define ST_SPF_LAST_EVENT_UP 0x2 504 #define ST_SPF_ETHERNET 0x4 505 #define ST_SPF_DISABLED 0x10000000 506 507 extern volatile uint32 bcm_st_atp_flags; 508 #ifndef BCM_ST_ATP_FLAGS_DEFAULT 509 #define BCM_ST_ATP_FLAGS_DEFAULT ATP_F_LEARN_SLF 510 #endif 511 512 extern int bcm_st_reserved_modid_enable_set(int value); 513 extern int bcm_st_reserved_modid_enable_get(void); 514 515 extern int bcm_st_transition(bcm_st_state_t from, 516 bcm_st_event_t event, 517 bcm_st_state_t to, 518 cpudb_ref_t disc_db, 519 cpudb_ref_t cur_db); 520 521 522 /* Event logging */ 523 SHARED_EVLOG_EXTERN(st_log) 524 525 extern cpudb_ref_t bcm_st_current_db_get(void); 526 extern cpudb_ref_t bcm_st_discovery_db_get(void); 527 528 #endif /* _STKTASK_H_ */