NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES
#include <ddi/phy/phy.h>
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.
DDI
Provides PHY device driver services.
typedef struct PhyOps { PhyVersion version; /* version number of the driver API */ KnError (*open) __((PhyId devId, void* clientCookie, PhyCallBack* clientCallbacks, PhyConfig* devConfig, PhyStatus* devStatus)); void (*close) __((PhyId devId)); void (*mask) __((PhyId devId)); void (*unmask) __((PhyId dev_id)); KnError (*negotiate) __((PhyId devId, PhyAutoCap cap, PhyConfig* config, PhyStatus* status, PhyAutoCap* partnerCap)); KnError (*configure) __((PhyId devId, PhyConfig config, PhyStatus* status)); } PhyOps;
A pointer to the PhyOps structure is exported by the driver via the svDeviceRegister() microkernel call. A driver client invokes the svDeviceLookup() and svDeviceEntry() microkernel calls in order to obtain a pointer to the device service routines vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via the indirect function call) in order to negotiate the status of the link.
open() opens a connection to a given phy transceiver driver. open() must be the first call to the device driver. When K_OK is returned, open() puts the device into an event masked state. In order to start device asynchronous notifification of events through callbacks, the unmask() down-call must be invoked. The open() routine is called with the following arguments:
phy device identifier.
Client handler cookie which is passed back to the client when a client call back handler is invoked.
Client call back handlers.
On return, it contains the current configuration of the phy device.
On return, it contains the current status of the phy device.
On succes K_OK is returned. The current phy device configuration is returned in the devConfig argument, and the current status of the phy device is returned in the devStatus argument.
On failure, an error code is returned as follow:
Not enough memory resources.
Another connection is already open for the given device.
close() closes the connection with a given a phy transceiver driver The close() routine is called with the following argument:
phy device identifier.
phy device identifier.
The unmask() function enables all events from device. Typically, the mask()/unmask() pair would be used by the driver client to implement a critical section of the code which is synchronized with the call-back handlers. The mask()/unmask() pair must not be called by the call-back handlers. Actually, it is not necessary because the events are already masked when a call-back handler is invoked. The mask()/unmask() pairs must not be nested. The unmask() routine is called with the following argument:
phy device identifier.
The negotiate() routine start auto-negotiation on a given phy transceiver. The negotiate() routine is called with the following arguments:
phy device identifier.
Indicates the controller capabilities, to be used for autonegotiation advertisement.
On return, it contains configuration of the phy device.
On return, it contains the status of the phy device.
On return, indicates which modes among those specified in cap argument are supported by the link partner.
On success it returns K_OK. config, status and partnerCap contains information about the configuration established after the negotiation.
On failure an error code is returned as follow:
Negotiation has failed. config, status and partnerCap give details about the reasons of failure.
The phy transceiver is not auto-negotiation able.
No one of the working modes specified in cap argument are supported by the phy transceiver.
The configure() routine enforce the configuration of a given phy transceiver. Note that the auto-negotiation will be disabled by this call. The configure() routine is called with the following arguments:
The phy device identifier.
Specified the required configuration of the phy device.
On return, it gives status of the phy transceiver.
On success, it returns K_OK and status contains the status of the phy transceiver.
On failure, an error code is returned as follow:
The configuration has failed.
The config passed as argument is not supported by the phy transceiver.
The phy transceiver status bits indicate the current link status. Informations can be retrieved with the following bit masks.
Parallel detection fault.
Remote fault condition detected.
Link failure condition detected.
Jabber condition detected (10BT only)
The phy transceiver configuration specifies the link speed, mode, and duplex mode. It can takes the following values:
10BASE-T half duplex
10BASE-T full duplex
100BASE-T4
100BASE-TX half duplex
100BASE-TX full duplex
100BASE-FX half duplex
100BASE-FX full duplex
It defines the controller capabilities to be used for auto-negotiation advertisement. The following bit masks can be used to retrieve information from a such value or to set a value.
If supported by the device, it enables the next page function during auto-negotiation.
Indicates a remote fault.
Pause operation in full duplex mode.
100BASE-T4 available.
100BASE-TX full duplex available.
100BASE-TX half duplex available.
10BASE-TX full duplex available.
10 BASE-TX half duplex available.
IEEE 802.3
IEEE 802.9 ISLAN-16T
When the client open a connection with the phy device, it gives as arguments a structure which contains call back handler. The PhyCallBack structure is defined as follows:
typedef struct PhyCallBack { void (*changeNotify) __((void* clientCookie, PhyConfig config, PhyStatus status, PhyAutoCap partnerCap)); } PhyCallBack;
The changeNotify() routine notifies the driver client that the transceiver state/configuration has changed asynchronously after:
The link status has changed.
The configuration/state is changed due to link partner.
The changeNotify() up-call may be issued from the interrupt level. This routine is called with the following arguments:
The client cookie which was given as arguments to open() by the driver client.
The current configuration of the phy transceiver.
The status of the phy transceiver.
Indicates the link partner ability.
Services | Base level | DKI thread | Interrupt | Blocking |
---|---|---|---|---|
PhyOps.open | + | + | - | - |
PhyOps.close | + | + | - | - |
PhyOps.mask | + | - | - | - |
PhyOps.unmask | + | - | - | - |
PhyOps.negotiate | + | + | - | + |
PhyOps.configure | + | + | - | + |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES