Since the blamed commit we don't have register_switch_driver() and unregister_switch_driver() anymore. Additionally, the expected dsa_register_switch() and dsa_unregister_switch() calls aren't documented. Update the probing section with the details of how things are currently done.
Unified · Split
| @@ -503,14 +503,74 @@ per-port PHY specific details: interface connection, MDIO bus location, etc. · 502 unmodified lines | |||
| 503 | Driver development | 503 | Driver development |
| 504 | ================== | 504 | ================== |
| 505 | 505 | ||
| 506 | DSA switch drivers need to implement a dsa_switch_ops structure which will | 506 | DSA switch drivers need to implement a ``dsa_switch_ops`` structure which will |
| 507 | contain the various members described below. | 507 | contain the various members described below. |
| 508 | 508 | ||
| 509 | ``register_switch_driver()`` registers this dsa_switch_ops in its internal list | 509 | Probing, registration and device lifetime |
| 510 | of drivers to probe for. ``unregister_switch_driver()`` does the exact opposite. | 510 | ----------------------------------------- |
| 511 | 511 | ||
| 512 | Unless requested differently by setting the priv_size member accordingly, DSA | 512 | DSA switches are regular ``device`` structures on buses (be they platform, SPI, |
| 513 | does not allocate any driver private context space. | 513 | I2C, MDIO or otherwise). The DSA framework is not involved in their probing |
| 514 | with the device core. | ||
| 515 | |||
| 516 | Switch registration from the perspective of a driver means passing a valid | ||
| 517 | ``struct dsa_switch`` pointer to ``dsa_register_switch()``, usually from the | ||
| 518 | switch driver's probing function. The following members must be valid in the | ||
| 519 | provided structure: | ||
| 520 | |||
| 521 | - ``ds->dev``: will be used to parse the switch's OF node or platform data. | ||
| 522 | |||
| 523 | - ``ds->num_ports``: will be used to create the port list for this switch, and | ||
| 524 | to validate the port indices provided in the OF node. | ||
| 525 | |||
| 526 | - ``ds->ops``: a pointer to the ``dsa_switch_ops`` structure holding the DSA | ||
| 527 | method implementations. | ||
| 528 | |||
| 529 | - ``ds->priv``: backpointer to a driver-private data structure which can be | ||
| 530 | retrieved in all further DSA method callbacks. | ||
| 531 | |||
| 532 | In addition, the following flags in the ``dsa_switch`` structure may optionally | ||
| 533 | be configured to obtain driver-specific behavior from the DSA core. Their | ||
| 534 | behavior when set is documented through comments in ``include/net/dsa.h``. | ||
| 535 | |||
| 536 | - ``ds->vlan_filtering_is_global`` | ||
| 537 | |||
| 538 | - ``ds->needs_standalone_vlan_filtering`` | ||
| 539 | |||
| 540 | - ``ds->configure_vlan_while_not_filtering`` | ||
| 541 | |||
| 542 | - ``ds->untag_bridge_pvid`` | ||
| 543 | |||
| 544 | - ``ds->assisted_learning_on_cpu_port`` | ||
| 545 | |||
| 546 | - ``ds->mtu_enforcement_ingress`` | ||
| 547 | |||
| 548 | - ``ds->fdb_isolation`` | ||
| 549 | |||
| 550 | Internally, DSA keeps an array of switch trees (group of switches) global to | ||
| 551 | the kernel, and attaches a ``dsa_switch`` structure to a tree on registration. | ||
| 552 | The tree ID to which the switch is attached is determined by the first u32 | ||
| 553 | number of the ``dsa,member`` property of the switch's OF node (0 if missing). | ||
| 554 | The switch ID within the tree is determined by the second u32 number of the | ||
| 555 | same OF property (0 if missing). Registering multiple switches with the same | ||
| 556 | switch ID and tree ID is illegal and will cause an error. Using platform data, | ||
| 557 | a single switch and a single switch tree is permitted. | ||
| 558 | |||
| 559 | In case of a tree with multiple switches, probing takes place asymmetrically. | ||
| 560 | The first N-1 callers of ``dsa_register_switch()`` only add their ports to the | ||
| 561 | port list of the tree (``dst->ports``), each port having a backpointer to its | ||
| 562 | associated switch (``dp->ds``). Then, these switches exit their | ||
| 563 | ``dsa_register_switch()`` call early, because ``dsa_tree_setup_routing_table()`` | ||
| 564 | has determined that the tree is not yet complete (not all ports referenced by | ||
| 565 | DSA links are present in the tree's port list). The tree becomes complete when | ||
| 566 | the last switch calls ``dsa_register_switch()``, and this triggers the effective | ||
| 567 | continuation of initialization (including the call to ``ds->ops->setup()``) for | ||
| 568 | all switches within that tree, all as part of the calling context of the last | ||
| 569 | switch's probe function. | ||
| 570 | |||
| 571 | The opposite of registration takes place when calling ``dsa_unregister_switch()``, | ||
| 572 | which removes a switch's ports from the port list of the tree. The entire tree | ||
| 573 | is torn down when the first switch unregisters. | ||
| 514 | 574 | ||
| 515 | Switch configuration | 575 | Switch configuration |
| 516 | -------------------- | 576 | -------------------- |
| @@ -518,12 +578,6 @@ Switch configuration · 1 unmodified line | |||
| 518 | - ``tag_protocol``: this is to indicate what kind of tagging protocol is supported, | 578 | - ``tag_protocol``: this is to indicate what kind of tagging protocol is supported, |
| 519 | should be a valid value from the ``dsa_tag_protocol`` enum | 579 | should be a valid value from the ``dsa_tag_protocol`` enum |
| 520 | 580 | ||
| 521 | - ``probe``: probe routine which will be invoked by the DSA platform device upon | ||
| 522 | registration to test for the presence/absence of a switch device. For MDIO | ||
| 523 | devices, it is recommended to issue a read towards internal registers using | ||
| 524 | the switch pseudo-PHY and return whether this is a supported device. For other | ||
| 525 | buses, return a non-NULL string | ||
| 526 | |||
| 527 | - ``setup``: setup function for the switch, this function is responsible for setting | 581 | - ``setup``: setup function for the switch, this function is responsible for setting |
| 528 | up the ``dsa_switch_ops`` private structure with all it needs: register maps, | 582 | up the ``dsa_switch_ops`` private structure with all it needs: register maps, |
| 529 | interrupts, mutexes, locks, etc. This function is also expected to properly | 583 | interrupts, mutexes, locks, etc. This function is also expected to properly |