@@ -10,21 +10,21 @@ in joining the effort.
1010Design principles
1111=================
1212
13- The Distributed Switch Architecture is a subsystem which was primarily designed
14- to support Marvell Ethernet switches (MV88E6xxx, a.k.a Linkstreet product line)
15- using Linux, but has since evolved to support other vendors as well.
13+ The Distributed Switch Architecture subsystem was primarily designed to
14+ support Marvell Ethernet switches (MV88E6xxx, a.k.a. Link Street product
15+ line) using Linux, but has since evolved to support other vendors as well.
1616
1717The original philosophy behind this design was to be able to use unmodified
1818Linux tools such as bridge, iproute2, ifconfig to work transparently whether
1919they configured/queried a switch port network device or a regular network
2020device.
2121
22- An Ethernet switch is typically comprised of multiple front-panel ports, and one
23- or more CPU or management port . The DSA subsystem currently relies on the
22+ An Ethernet switch typically comprises multiple front-panel ports and one
23+ or more CPU or management ports . The DSA subsystem currently relies on the
2424presence of a management port connected to an Ethernet controller capable of
2525receiving Ethernet frames from the switch. This is a very common setup for all
2626kinds of Ethernet switches found in Small Home and Office products: routers,
27- gateways, or even top-of-the rack switches. This host Ethernet controller will
27+ gateways, or even top-of-rack switches. This host Ethernet controller will
2828be later referred to as "master" and "cpu" in DSA terminology and code.
2929
3030The D in DSA stands for Distributed, because the subsystem has been designed
@@ -33,14 +33,14 @@ using upstream and downstream Ethernet links between switches. These specific
3333ports are referred to as "dsa" ports in DSA terminology and code. A collection
3434of multiple switches connected to each other is called a "switch tree".
3535
36- For each front-panel port, DSA will create specialized network devices which are
36+ For each front-panel port, DSA creates specialized network devices which are
3737used as controlling and data-flowing endpoints for use by the Linux networking
3838stack. These specialized network interfaces are referred to as "slave" network
3939interfaces in DSA terminology and code.
4040
4141The ideal case for using DSA is when an Ethernet switch supports a "switch tag"
4242which is a hardware feature making the switch insert a specific tag for each
43- Ethernet frames it received to/from specific ports to help the management
43+ Ethernet frame it receives to/from specific ports to help the management
4444interface figure out:
4545
4646- what port is this frame coming from
@@ -125,7 +125,7 @@ other switches from the same fabric, and in this case, the outermost switch
125125ports must decapsulate the packet.
126126
127127Note that in certain cases, it might be the case that the tagging format used
128- by a leaf switch (not connected directly to the CPU) to not be the same as what
128+ by a leaf switch (not connected directly to the CPU) is not the same as what
129129the network stack sees. This can be seen with Marvell switch trees, where the
130130CPU port can be configured to use either the DSA or the Ethertype DSA (EDSA)
131131format, but the DSA links are configured to use the shorter (without Ethertype)
@@ -270,21 +270,21 @@ These interfaces are specialized in order to:
270270 to/from specific switch ports
271271- query the switch for ethtool operations: statistics, link state,
272272 Wake-on-LAN, register dumps...
273- - external/internal PHY management : link, auto-negotiation etc.
273+ - manage external/internal PHY: link, auto-negotiation, etc.
274274
275275These slave network devices have custom net_device_ops and ethtool_ops function
276276pointers which allow DSA to introduce a level of layering between the networking
277- stack/ethtool, and the switch driver implementation.
277+ stack/ethtool and the switch driver implementation.
278278
279279Upon frame transmission from these slave network devices, DSA will look up which
280- switch tagging protocol is currently registered with these network devices, and
280+ switch tagging protocol is currently registered with these network devices and
281281invoke a specific transmit routine which takes care of adding the relevant
282282switch tag in the Ethernet frames.
283283
284284These frames are then queued for transmission using the master network device
285- ``ndo_start_xmit() `` function, since they contain the appropriate switch tag, the
285+ ``ndo_start_xmit() `` function. Since they contain the appropriate switch tag, the
286286Ethernet switch will be able to process these incoming frames from the
287- management interface and delivers these frames to the physical switch port.
287+ management interface and deliver them to the physical switch port.
288288
289289Graphical representation
290290------------------------
@@ -330,9 +330,9 @@ MDIO reads/writes towards specific PHY addresses. In most MDIO-connected
330330switches, these functions would utilize direct or indirect PHY addressing mode
331331to return standard MII registers from the switch builtin PHYs, allowing the PHY
332332library and/or to return link status, link partner pages, auto-negotiation
333- results etc. .
333+ results, etc.
334334
335- For Ethernet switches which have both external and internal MDIO busses , the
335+ For Ethernet switches which have both external and internal MDIO buses , the
336336slave MII bus can be utilized to mux/demux MDIO reads and writes towards either
337337internal or external MDIO devices this switch might be connected to: internal
338338PHYs, external PHYs, or even external switches.
@@ -349,7 +349,7 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as
349349 table indication (when cascading switches)
350350
351351- ``dsa_platform_data ``: platform device configuration data which can reference
352- a collection of dsa_chip_data structure if multiples switches are cascaded,
352+ a collection of dsa_chip_data structures if multiple switches are cascaded,
353353 the master network device this switch tree is attached to needs to be
354354 referenced
355355
@@ -426,7 +426,7 @@ logic basically looks like this:
426426 "phy-handle" property, if found, this PHY device is created and registered
427427 using ``of_phy_connect() ``
428428
429- - if Device Tree is used, and the PHY device is "fixed", that is, conforms to
429+ - if Device Tree is used and the PHY device is "fixed", that is, conforms to
430430 the definition of a non-MDIO managed PHY as defined in
431431 ``Documentation/devicetree/bindings/net/fixed-link.txt ``, the PHY is registered
432432 and connected transparently using the special fixed MDIO bus driver
@@ -481,7 +481,7 @@ Device Tree
481481DSA features a standardized binding which is documented in
482482``Documentation/devicetree/bindings/net/dsa/dsa.txt ``. PHY/MDIO library helper
483483functions such as ``of_get_phy_mode() ``, ``of_phy_connect() `` are also used to query
484- per-port PHY specific details: interface connection, MDIO bus location etc. .
484+ per-port PHY specific details: interface connection, MDIO bus location, etc.
485485
486486Driver development
487487==================
@@ -509,7 +509,7 @@ Switch configuration
509509
510510- ``setup ``: setup function for the switch, this function is responsible for setting
511511 up the ``dsa_switch_ops `` private structure with all it needs: register maps,
512- interrupts, mutexes, locks etc. . This function is also expected to properly
512+ interrupts, mutexes, locks, etc. This function is also expected to properly
513513 configure the switch to separate all network interfaces from each other, that
514514 is, they should be isolated by the switch hardware itself, typically by creating
515515 a Port-based VLAN ID for each port and allowing only the CPU port and the
@@ -526,13 +526,13 @@ PHY devices and link management
526526- ``get_phy_flags ``: Some switches are interfaced to various kinds of Ethernet PHYs,
527527 if the PHY library PHY driver needs to know about information it cannot obtain
528528 on its own (e.g.: coming from switch memory mapped registers), this function
529- should return a 32-bits bitmask of "flags", that is private between the switch
529+ should return a 32-bit bitmask of "flags" that is private between the switch
530530 driver and the Ethernet PHY driver in ``drivers/net/phy/\* ``.
531531
532532- ``phy_read ``: Function invoked by the DSA slave MDIO bus when attempting to read
533533 the switch port MDIO registers. If unavailable, return 0xffff for each read.
534534 For builtin switch Ethernet PHYs, this function should allow reading the link
535- status, auto-negotiation results, link partner pages etc. .
535+ status, auto-negotiation results, link partner pages, etc.
536536
537537- ``phy_write ``: Function invoked by the DSA slave MDIO bus when attempting to write
538538 to the switch port MDIO registers. If unavailable return a negative error
@@ -554,7 +554,7 @@ Ethtool operations
554554------------------
555555
556556- ``get_strings ``: ethtool function used to query the driver's strings, will
557- typically return statistics strings, private flags strings etc.
557+ typically return statistics strings, private flags strings, etc.
558558
559559- ``get_ethtool_stats ``: ethtool function used to query per-port statistics and
560560 return their values. DSA overlays slave network devices general statistics:
@@ -564,7 +564,7 @@ Ethtool operations
564564- ``get_sset_count ``: ethtool function used to query the number of statistics items
565565
566566- ``get_wol ``: ethtool function used to obtain Wake-on-LAN settings per-port, this
567- function may, for certain implementations also query the master network device
567+ function may for certain implementations also query the master network device
568568 Wake-on-LAN settings if this interface needs to participate in Wake-on-LAN
569569
570570- ``set_wol ``: ethtool function used to configure Wake-on-LAN settings per-port,
@@ -607,27 +607,27 @@ Power management
607607 in a fully active state
608608
609609- ``port_enable ``: function invoked by the DSA slave network device ndo_open
610- function when a port is administratively brought up, this function should be
611- fully enabling a given switch port. DSA takes care of marking the port with
610+ function when a port is administratively brought up, this function should
611+ fully enable a given switch port. DSA takes care of marking the port with
612612 ``BR_STATE_BLOCKING `` if the port is a bridge member, or ``BR_STATE_FORWARDING `` if it
613613 was not, and propagating these changes down to the hardware
614614
615615- ``port_disable ``: function invoked by the DSA slave network device ndo_close
616- function when a port is administratively brought down, this function should be
617- fully disabling a given switch port. DSA takes care of marking the port with
616+ function when a port is administratively brought down, this function should
617+ fully disable a given switch port. DSA takes care of marking the port with
618618 ``BR_STATE_DISABLED `` and propagating changes to the hardware if this port is
619619 disabled while being a bridge member
620620
621621Bridge layer
622622------------
623623
624624- ``port_bridge_join ``: bridge layer function invoked when a given switch port is
625- added to a bridge, this function should be doing the necessary at the switch
626- level to permit the joining port from being added to the relevant logical
625+ added to a bridge, this function should do what's necessary at the switch
626+ level to permit the joining port to be added to the relevant logical
627627 domain for it to ingress/egress traffic with other members of the bridge.
628628
629629- ``port_bridge_leave ``: bridge layer function invoked when a given switch port is
630- removed from a bridge, this function should be doing the necessary at the
630+ removed from a bridge, this function should do what's necessary at the
631631 switch level to deny the leaving port from ingress/egress traffic from the
632632 remaining bridge members. When the port leaves the bridge, it should be aged
633633 out at the switch hardware for the switch to (re) learn MAC addresses behind
@@ -663,7 +663,7 @@ Bridge layer
663663 point for drivers that need to configure the hardware for enabling this
664664 feature.
665665
666- - ``port_bridge_tx_fwd_unoffload ``: bridge layer function invoken when a driver
666+ - ``port_bridge_tx_fwd_unoffload ``: bridge layer function invoked when a driver
667667 leaves a bridge port which had the TX forwarding offload feature enabled.
668668
669669Bridge VLAN filtering
0 commit comments