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 | 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 | 507 | contain the various members described below. |
| 508 | 508 | |
| 509 | −``register_switch_driver()`` registers this dsa_switch_ops in its internal list | |
| 510 | −of drivers to probe for. ``unregister_switch_driver()`` does the exact opposite. | |
| 509 | +Probing, registration and device lifetime | |
| 510 | +----------------------------------------- | |
| 511 | 511 | |
| 512 | −Unless requested differently by setting the priv_size member accordingly, DSA | |
| 513 | −does not allocate any driver private context space. | |
| 512 | +DSA switches are regular ``device`` structures on buses (be they platform, SPI, | |
| 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 | 575 | Switch configuration |
| 516 | 576 | -------------------- |
| @@ -518,12 +578,6 @@ Switch configuration · 1 unmodified line | ||
| 518 | 578 | - ``tag_protocol``: this is to indicate what kind of tagging protocol is supported, |
| 519 | 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 | 581 | - ``setup``: setup function for the switch, this function is responsible for setting |
| 528 | 582 | up the ``dsa_switch_ops`` private structure with all it needs: register maps, |
| 529 | 583 | interrupts, mutexes, locks, etc. This function is also expected to properly |