mii(9ddi)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
NAME
- mii- Media Independent Interface
Bus Driver Interface
SYNOPSIS
#include &ddi/mii/mii.h>
API RESTRICTIONS
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
FEATURES
DDI
DESCRIPTION
Provides MII bus driver interface services.
EXTENDED DESCRIPTION
-
MII bus/PHY device driver connection establishment.
-
MII bus management interrupt connection/disconnection.
-
PHY registers access.
The MII bus (IEEE 802.3u) is a generic bus that connects different types of PHYs (network physical transceivers) to the same network controller. The network controller may interact with any PHY using the same hardware interface, independent of the media the PHYs are connected to.
The MII bus driver API enables development of portable PHY device drivers. These drivers may be reused provided that a MII bus driver is available.
Note that such a PHY device driver may be integrated into the Ethernet device driver, or built as a separate driver and connected to the Ethernet device driver through the device registry.
The MII bus driver interface provides the following services to the PHY device drivers:
A PHY device driver connected to a MII bus specifies the "mii" parent class in the driver entry. In such a case, a bus driver supporting the MII interface would invoke the driver initialization routine if a device serviced by the driver resides on the bus. The MII bus driver gives a MiiOps/MiiId pair to the device driver initialization routine. The MiiOps/MiiId pair specifies a bus driver instance which provides the MII Bus Driver Interface.
The MiiOps structure contains pointers to the MII bus driver service routines.
The MiiOps structure is the following:
typedef struct MiiOps {
MiiVersion version;
KnError
(*open) (MiiId miiId,
DevNode devNode,
MiiEventHandler devEventHandler,
MiiLoadHandler devLoadHandler,
void* devCookie,
MiiDevId* devId);
void
(*close) (MiiDevId devId);
KnError
(*intr_attach) (MiiDevId devId,
MiiIntrHandler devIntrHandler,
void* devIntrCookie,
MiiIntrOps** intrOps,
MiiIntrId* intrId);
void
(*intr_detach) (MiiIntrId intrId);
uint16_f
(*reg_load) (MiiDevId devId, MiiReg reg);
void
(*reg_store) (MiiDevId devId, MiiReg reg, uint16_f val);
} MiiOps;
- version
-
The version field specifies the MII bus driver API version number. Each time one of the MII bus driver structures is extended the version number is incremented to include new service routines. So, each time this type of an API extension is performed, a new symbol is added to the MiiVersion (for example, MII_VERSION_1) . Obviously, all extensions made in the bus driver API must be explicitly documented.
A PHY device driver specifies a minimal API version number required by the driver within its registry entry. The PHY device driver initialization routine is not invoked by the MII bus driver if the API version number provided by the MII bus driver is less than the API version number specified within the device driver registry entry.
- open()/close()
-
The open() operation must be the first call issued by the PHY device driver to the bus driver. It establishes a connection between the device and the MII bus driver.
The MiiId is an opaque parameter of the device driver, specifying the MII bus driver instance. It must be passed back to the bus driver as an argument of the open() routine.
The devNode argument specifies the device node (in the device tree) which is serviced by the PHY device driver instance. For initialization, the device node is given as an argument of drv_init() by the parent MII bus driver. For probing, the device node is either:
-
located among existing child nodes attached to the parent node.
-
created (and attached to the parent node) by the device driver.
The devEventHandler argument specifies the device driver handler which is invoked by the MII bus driver when a bus event occurs. Typically, devEventHandler is called as an interrupt handler and therefore the handler implementation must be restricted to APIs allowed at interrupt level.
The devCookie, an opaque argument of the MII bus driver, argument specifies a device driver cookie. devCookie is passed back to the PHY device driver when devEventHandler or devLoadHandler is invoked.
The devLoadHandler optional argument specifies the driver handler which is invoked by the MII bus driver when a new driver has been dynamically loaded.
MII bus events are inherited from the Common Bus DDI, bus(9DDI) for a detailed description of devEventHandler, devLoadHandler and their respective usage.
Upon successful completion, the MII bus driver returns a MiiDevId identifier, designating the MII bus/ PHY device connection. MiiDevId is opaque for the PHY device driver. It must be passed back to the MII bus driver as an argument in subsequent invocations of the MiiOps service routines.
In case of failure, an error code is returned as follows:
- K_EINVAL
-
The devNode argument given is not a valid device tree node, or the device node does not contain the required MII_PROP_PHY_ADDR property.
- K_EBUSY
-
The devNode device tree node given is already in use (associated with another driver).
- K_ENOMEM
-
The system is out of memory.
The close() routine releases the MII bus/ PHY driver connection. It must be the last call issued to the MII bus driver.
-
- intr_attach()/intr_detach()
-
The intr_attach() service routine connects the PHY device driver specific handler to the MII bus management interrupt source. The devId argument identifies the PHY device on the MII bus. It is an opaque returned by open().
The devIntrHandler argument specifies the interrupt handler invoked by the MII bus driver when a management interrupt occurs. The devIntrCookie specifies an argument which is passed back to the interrupt handler.
If successful, the bus driver returns an intrOps / intrId pair. intrOps points to the MiiIntrOps structure which provides the service routines specific to the MII bus management interrupt source. intrId is opaque for the device driver. It must be passed back to the MII bus driver as an argument in subsequent invocations of the intrOps and intrDetach() service routines.
Note that devIntrHandler() prototype and MiiIntrOps services are inherited from Common Bus Interface. Refer to bus(9ddi) for a detailed description of these operations, their behaviour and usage.
When the MII bus driver returns successfully from intrAttach(), the corresponding interrupt source is enabled at bus level. In case of failure, an error code is returned as described below:
- K_ENOTIMP
-
The MII management interrupt is not available.
- K_EBUSY
-
The PHY device driver is already attached to the MII management interrupt.
- K_ENOMEM
-
The system is out of memory.
The intrDetach() service routine disconnects the interrupt handler from the MII management interrupt source. In other words, the corresponding interrupt handler is no longer invoked when management interrupts occur. intrId() specifies the MII bus driver handle returned by intrAttach().
- reg_load() / reg_store()
-
The reg_load() service routine is used to read the value from a register of the PHY device. The reg_store() service routine is used to write a new value into a register of the PHY device.
The devId argument identifies the PHY device on the MII bus. It is an opaque value, returned by open().
The reg argument identifies the register to be read or written. The register is identified by its number within the PHY register set. Registers numbered from 0 to 6 are standard MII registers. Other register numbers may be defined for a given PHY implementation. However, using such specific registers leads to a non-portable PHY device driver (another PHY device may not implement the same specific registers). Also, note that not all standard registers are mandatory. Only a subset may be implemented by a given PHY device.
The following MII bus standard registers are defined by the DDI. Refer to the mii.h header file or IEEE 802.3u document for a definition of register's bits and their usage.
Alias Number Description MII_CTRL_REG 0x00 Control register MII_STAT_REG 0x01 Status register MII_PHY1_REG 0x02 PHY identification #1 register MII_PHY2_REG 0x03 PHY identification #2 register MII_NEG_ADV_REG 0x04 Auto-negotiation advertisement register MII_NEG_PAR_REG 0x05 Auto-negotiation link partner ability register MII_NEG_EXP_REG 0x06 Auto-negotiation expansion register Values returned by reg_load() or passed into reg_store()'s val argument are 16-bit unsigned integers. On error, for example a number that is invalidly registered, access is ignored for a store and an unpredictable value is returned for a load (usually 0xffff).
MII Bus Resource Properties
Bus resources used by the PHY device are specified as properties attached to the device node. The table below lists device node properties defined by the MII bus interface. Note that the column "m/o" specifies whether a given property is mandatory or optional.
| Alias | Name | Value | m/o |
|---|---|---|---|
| MII_PROP_PHY_ADDR | "phy-addr" | MiiPropPhyAddr | m |
| MII_PROP_PHY_ID | "phy-id" | MiiPropPhyId | o |
The MII_PROP_PHY_ADDR property specifies the PHY device address on the MII bus. Only the 5 least significant bits are used, forming 5 bit MII bus addresses. This address uniquely identifies a given PHY device on the MII bus.
The MII_PROP_PHY_ID property specifies a standardized manufacturer identifier for a PHY device. It is made of an OUI, a model and a revision mask. This ID uniquely identifies a PHY device and may be used for device/driver binding.
Allowed Calling Contexts
The following table specifies the contexts in which a caller is allowed to invoke each service:
| Services | Base level | DKI thread | Interrupt | Blocking |
|---|---|---|---|---|
| MiiOps.open | -- | + | -- | + |
| MiiOps.close | -- | + | + | + |
| MiiOps.intr_attach | -- | + | -- | + |
| MiiOps.intr_detach | -- | + | -- | + |
| BusIntrOps.mask | + | + | + | -- |
| BusIntrOps.unmask | + | + | + | -- |
| BusIntrOps.enable | -- | -- | + | -- |
| BusIntrOps.disable | -- | -- | + | -- |
| MiiOps.reg_load | + | + | + | -- |
| MiiOps.reg_store | + | + | + | -- |
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|---|---|
| Interface Stability | Evolving |
SEE ALSO
bus(9DDI), phy(9DDI), ether(9DDI)
phy(9DDI), Ether(9DDI)
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
- © 2010, Oracle Corporation and/or its affiliates