Skip to content

Commit

Permalink
sfp: add documentation for kernel APIs
Browse files Browse the repository at this point in the history 
Add kernel-doc documentation for sfp kernel APIs, and link it into the
networking kapi documentation under "Network device support".

Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
Reviewed-by: Florian Fainelli <f.fainelli@gmail.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
  • Loading branch information
Russell King authored and David S. Miller committed Dec 5, 2017
1 parent 8796c89 commit 0a6fcd3
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 14 deletions.
12 changes: 12 additions & 0 deletions Documentation/networking/kapi.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,3 +157,15 @@ PHYLINK
:internal:

.. kernel-doc:: drivers/net/phy/phylink.c

SFP support
-----------

.. kernel-doc:: drivers/net/phy/sfp-bus.c
:internal:

.. kernel-doc:: include/linux/sfp.h
:internal:

.. kernel-doc:: drivers/net/phy/sfp-bus.c
:export:
104 changes: 104 additions & 0 deletions drivers/net/phy/sfp-bus.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@

#include "sfp.h"

/**
* struct sfp_bus - internal representation of a sfp bus
*/
struct sfp_bus {
/* private: */
struct kref kref;
struct list_head node;
struct device_node *device_node;
Expand All @@ -26,6 +30,20 @@ struct sfp_bus {
bool started;
};

/**
* sfp_parse_port() - Parse the EEPROM base ID, setting the port type
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
* @id: a pointer to the module's &struct sfp_eeprom_id
* @support: optional pointer to an array of unsigned long for the
* ethtool support mask
*
* Parse the EEPROM identification given in @id, and return one of
* %PORT_TP, %PORT_FIBRE or %PORT_OTHER. If @support is non-%NULL,
* also set the ethtool %ETHTOOL_LINK_MODE_xxx_BIT corresponding with
* the connector type.
*
* If the port type is not known, returns %PORT_OTHER.
*/
int sfp_parse_port(struct sfp_bus *bus, const struct sfp_eeprom_id *id,
unsigned long *support)
{
Expand Down Expand Up @@ -78,6 +96,24 @@ int sfp_parse_port(struct sfp_bus *bus, const struct sfp_eeprom_id *id,
}
EXPORT_SYMBOL_GPL(sfp_parse_port);

/**
* sfp_parse_interface() - Parse the phy_interface_t
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
* @id: a pointer to the module's &struct sfp_eeprom_id
*
* Derive the phy_interface_t mode for the information found in the
* module's identifying EEPROM. There is no standard or defined way
* to derive this information, so we use some heuristics.
*
* If the encoding is 64b66b, then the module must be >= 10G, so
* return %PHY_INTERFACE_MODE_10GKR.
*
* If it's 8b10b, then it's 1G or slower. If it's definitely a fibre
* module, return %PHY_INTERFACE_MODE_1000BASEX mode, otherwise return
* %PHY_INTERFACE_MODE_SGMII mode.
*
* If the encoding is not known, return %PHY_INTERFACE_MODE_NA.
*/
phy_interface_t sfp_parse_interface(struct sfp_bus *bus,
const struct sfp_eeprom_id *id)
{
Expand Down Expand Up @@ -117,6 +153,15 @@ phy_interface_t sfp_parse_interface(struct sfp_bus *bus,
}
EXPORT_SYMBOL_GPL(sfp_parse_interface);

/**
* sfp_parse_support() - Parse the eeprom id for supported link modes
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
* @id: a pointer to the module's &struct sfp_eeprom_id
* @support: pointer to an array of unsigned long for the ethtool support mask
*
* Parse the EEPROM identification information and derive the supported
* ethtool link modes for the module.
*/
void sfp_parse_support(struct sfp_bus *bus, const struct sfp_eeprom_id *id,
unsigned long *support)
{
Expand Down Expand Up @@ -293,6 +338,16 @@ static void sfp_unregister_bus(struct sfp_bus *bus)
bus->registered = false;
}

/**
* sfp_get_module_info() - Get the ethtool_modinfo for a SFP module
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
* @modinfo: a &struct ethtool_modinfo
*
* Fill in the type and eeprom_len parameters in @modinfo for a module on
* the sfp bus specified by @bus.
*
* Returns 0 on success or a negative errno number.
*/
int sfp_get_module_info(struct sfp_bus *bus, struct ethtool_modinfo *modinfo)
{
if (!bus->registered)
Expand All @@ -301,6 +356,17 @@ int sfp_get_module_info(struct sfp_bus *bus, struct ethtool_modinfo *modinfo)
}
EXPORT_SYMBOL_GPL(sfp_get_module_info);

/**
* sfp_get_module_eeprom() - Read the SFP module EEPROM
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
* @ee: a &struct ethtool_eeprom
* @data: buffer to contain the EEPROM data (must be at least @ee->len bytes)
*
* Read the EEPROM as specified by the supplied @ee. See the documentation
* for &struct ethtool_eeprom for the region to be read.
*
* Returns 0 on success or a negative errno number.
*/
int sfp_get_module_eeprom(struct sfp_bus *bus, struct ethtool_eeprom *ee,
u8 *data)
{
Expand All @@ -310,6 +376,15 @@ int sfp_get_module_eeprom(struct sfp_bus *bus, struct ethtool_eeprom *ee,
}
EXPORT_SYMBOL_GPL(sfp_get_module_eeprom);

/**
* sfp_upstream_start() - Inform the SFP that the network device is up
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
*
* Inform the SFP socket that the network device is now up, so that the
* module can be enabled by allowing TX_DISABLE to be deasserted. This
* should be called from the network device driver's &struct net_device_ops
* ndo_open() method.
*/
void sfp_upstream_start(struct sfp_bus *bus)
{
if (bus->registered)
Expand All @@ -318,6 +393,15 @@ void sfp_upstream_start(struct sfp_bus *bus)
}
EXPORT_SYMBOL_GPL(sfp_upstream_start);

/**
* sfp_upstream_stop() - Inform the SFP that the network device is down
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
*
* Inform the SFP socket that the network device is now up, so that the
* module can be disabled by asserting TX_DISABLE, disabling the laser
* in optical modules. This should be called from the network device
* driver's &struct net_device_ops ndo_stop() method.
*/
void sfp_upstream_stop(struct sfp_bus *bus)
{
if (bus->registered)
Expand All @@ -326,6 +410,19 @@ void sfp_upstream_stop(struct sfp_bus *bus)
}
EXPORT_SYMBOL_GPL(sfp_upstream_stop);

/**
* sfp_register_upstream() - Register the neighbouring device
* @np: device node for the SFP bus
* @ndev: network device associated with the interface
* @upstream: the upstream private data
* @ops: the upstream's &struct sfp_upstream_ops
*
* Register the upstream device (eg, PHY) with the SFP bus. MAC drivers
* should use phylink, which will call this function for them. Returns
* a pointer to the allocated &struct sfp_bus.
*
* On error, returns %NULL.
*/
struct sfp_bus *sfp_register_upstream(struct device_node *np,
struct net_device *ndev, void *upstream,
const struct sfp_upstream_ops *ops)
Expand Down Expand Up @@ -353,6 +450,13 @@ struct sfp_bus *sfp_register_upstream(struct device_node *np,
}
EXPORT_SYMBOL_GPL(sfp_register_upstream);

/**
* sfp_unregister_upstream() - Unregister sfp bus
* @bus: a pointer to the &struct sfp_bus structure for the sfp module
*
* Unregister a previously registered upstream connection for the SFP
* module. @bus is returned from sfp_register_upstream().
*/
void sfp_unregister_upstream(struct sfp_bus *bus)
{
rtnl_lock();
Expand Down
50 changes: 36 additions & 14 deletions include/linux/sfp.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

#include <linux/phy.h>

struct __packed sfp_eeprom_base {
struct sfp_eeprom_base {
u8 phys_id;
u8 phys_ext_id;
u8 connector;
Expand Down Expand Up @@ -166,12 +166,12 @@ struct __packed sfp_eeprom_base {
union {
__be16 optical_wavelength;
u8 cable_spec;
};
} __packed;
u8 reserved62;
u8 cc_base;
};
} __packed;

struct __packed sfp_eeprom_ext {
struct sfp_eeprom_ext {
__be16 options;
u8 br_max;
u8 br_min;
Expand All @@ -181,12 +181,21 @@ struct __packed sfp_eeprom_ext {
u8 enhopts;
u8 sff8472_compliance;
u8 cc_ext;
};

struct __packed sfp_eeprom_id {
} __packed;

/**
* struct sfp_eeprom_id - raw SFP module identification information
* @base: base SFP module identification structure
* @ext: extended SFP module identification structure
*
* See the SFF-8472 specification and related documents for the definition
* of these structure members. This can be obtained from
* ftp://ftp.seagate.com/sff
*/
struct sfp_eeprom_id {
struct sfp_eeprom_base base;
struct sfp_eeprom_ext ext;
};
} __packed;

/* SFP EEPROM registers */
enum {
Expand Down Expand Up @@ -353,13 +362,26 @@ struct ethtool_modinfo;
struct net_device;
struct sfp_bus;

/**
* struct sfp_upstream_ops - upstream operations structure
* @module_insert: called after a module has been detected to determine
* whether the module is supported for the upstream device.
* @module_remove: called after the module has been removed.
* @link_down: called when the link is non-operational for whatever
* reason.
* @link_up: called when the link is operational.
* @connect_phy: called when an I2C accessible PHY has been detected
* on the module.
* @disconnect_phy: called when a module with an I2C accessible PHY has
* been removed.
*/
struct sfp_upstream_ops {
int (*module_insert)(void *, const struct sfp_eeprom_id *id);
void (*module_remove)(void *);
void (*link_down)(void *);
void (*link_up)(void *);
int (*connect_phy)(void *, struct phy_device *);
void (*disconnect_phy)(void *);
int (*module_insert)(void *priv, const struct sfp_eeprom_id *id);
void (*module_remove)(void *priv);
void (*link_down)(void *priv);
void (*link_up)(void *priv);
int (*connect_phy)(void *priv, struct phy_device *);
void (*disconnect_phy)(void *priv);
};

#if IS_ENABLED(CONFIG_SFP)
Expand Down

0 comments on commit 0a6fcd3

Please sign in to comment.