Linux Networking and Network Devices APIs¶
Linux Networking¶
Networking Base Types¶
-
enum
sock_type
¶ Socket types
Constants
SOCK_STREAM
stream (connection) socket
SOCK_DGRAM
datagram (conn.less) socket
SOCK_RAW
raw socket
SOCK_RDM
reliably-delivered message
SOCK_SEQPACKET
sequential packet socket
SOCK_DCCP
Datagram Congestion Control Protocol socket
SOCK_PACKET
linux specific way of getting packets at the dev level. For writing rarp and other similar things on the user level.
Description
When adding some new socket type please grep ARCH_HAS_SOCKET_TYPE include/asm-* /socket.h, at least MIPS overrides this enum for binary compat reasons.
-
enum
sock_shutdown_cmd
¶ Shutdown types
Constants
SHUT_RD
shutdown receptions
SHUT_WR
shutdown transmissions
SHUT_RDWR
shutdown receptions/transmissions
-
struct
socket
¶ general BSD socket
Definition
struct socket {
socket_state state;
short type;
unsigned long flags;
struct file *file;
struct sock *sk;
const struct proto_ops *ops;
struct socket_wq wq;
};
Members
state
socket state (
SS_CONNECTED
, etc)type
socket type (
SOCK_STREAM
, etc)flags
socket flags (
SOCK_NOSPACE
, etc)file
File back pointer for gc
sk
internal networking protocol agnostic socket representation
ops
protocol specific socket operations
wq
wait queue for several uses
Socket Buffer Functions¶
Error
kernel-doc missing
Error
kernel-doc missing
-
struct file *
sock_alloc_file
(struct socket *sock, int flags, const char *dname)¶ Bind a
socket
to afile
Parameters
struct socket *sock
socket
int flags
file status flags
const char *dname
protocol name
Returns the
file
bound with sock, implicitly storing it in sock->file. If dname isNULL
, sets to “”. On failure the return is a ERR pointer (see linux/err.h). This function uses GFP_KERNEL internally.
Parameters
struct file *file
file
On failure returns
NULL
.
Parameters
int fd
file handle
int *err
pointer to an error code return
The file handle passed in is locked and the socket it is bound to is returned. If an error occurs the err pointer is overwritten with a negative errno code and NULL is returned. The function checks for both invalid handles and passing a handle which is not a socket.
On a success the socket object pointer is returned.
Parameters
void
no arguments
Description
Allocate a new inode and socket object. The two are bound together and initialised. The socket is then returned. If we are out of inodes NULL is returned. This functions uses GFP_KERNEL internally.
Parameters
struct socket *sock
socket to close
The socket is released from the protocol stack if it has a release callback, and the inode is then released if the socket is bound to an inode not a file.
Parameters
struct socket *sock
socket
struct msghdr *msg
message to send
Sends msg through sock, passing through LSM. Returns the number of bytes sent, or an error code.
-
int
kernel_sendmsg
(struct socket *sock, struct msghdr *msg, struct kvec *vec, size_t num, size_t size)¶ send a message through sock (kernel-space)
Parameters
struct socket *sock
socket
struct msghdr *msg
message header
struct kvec *vec
kernel vec
size_t num
vec array length
size_t size
total message data size
Builds the message data with vec and sends it through sock. Returns the number of bytes sent, or an error code.
-
int
kernel_sendmsg_locked
(struct sock *sk, struct msghdr *msg, struct kvec *vec, size_t num, size_t size)¶ send a message through sock (kernel-space)
Parameters
struct sock *sk
sock
struct msghdr *msg
message header
struct kvec *vec
output s/g array
size_t num
output s/g array length
size_t size
total message data size
Builds the message data with vec and sends it through sock. Returns the number of bytes sent, or an error code. Caller must hold sk.
Parameters
struct socket *sock
socket
struct msghdr *msg
message to receive
int flags
message flags
Receives msg from sock, passing through LSM. Returns the total number of bytes received, or an error.
-
int
kernel_recvmsg
(struct socket *sock, struct msghdr *msg, struct kvec *vec, size_t num, size_t size, int flags)¶ Receive a message from a socket (kernel space)
Parameters
struct socket *sock
The socket to receive the message from
struct msghdr *msg
Received message
struct kvec *vec
Input s/g array for message data
size_t num
Size of input s/g array
size_t size
Number of bytes to read
int flags
Message flags (MSG_DONTWAIT, etc…)
On return the msg structure contains the scatter/gather array passed in the vec argument. The array is modified so that it consists of the unfilled portion of the original array.
The returned value is the total number of bytes received, or an error.
Parameters
int family
protocol family (AF_INET, …)
int type
communication type (SOCK_STREAM, …)
int protocol
protocol (0, …)
struct socket **res
new socket
Creates a new socket and assigns it to res, passing through LSM. The new socket initialization is not complete, see
kernel_accept()
. Returns 0 or an error. On failure res is set toNULL
. This function internally uses GFP_KERNEL.
-
int
__sock_create
(struct net *net, int family, int type, int protocol, struct socket **res, int kern)¶ creates a socket
Parameters
struct net *net
net namespace
int family
protocol family (AF_INET, …)
int type
communication type (SOCK_STREAM, …)
int protocol
protocol (0, …)
struct socket **res
new socket
int kern
boolean for kernel space sockets
Creates a new socket and assigns it to res, passing through LSM. Returns 0 or an error. On failure res is set to
NULL
. kern must be set to true if the socket resides in kernel space. This function internally uses GFP_KERNEL.
Parameters
int family
protocol family (AF_INET, …)
int type
communication type (SOCK_STREAM, …)
int protocol
protocol (0, …)
struct socket **res
new socket
A wrapper around
__sock_create()
. Returns 0 or an error. This function internally uses GFP_KERNEL.
-
int
sock_create_kern
(struct net *net, int family, int type, int protocol, struct socket **res)¶ creates a socket (kernel space)
Parameters
struct net *net
net namespace
int family
protocol family (AF_INET, …)
int type
communication type (SOCK_STREAM, …)
int protocol
protocol (0, …)
struct socket **res
new socket
A wrapper around
__sock_create()
. Returns 0 or an error. This function internally uses GFP_KERNEL.
-
int
sock_register
(const struct net_proto_family *ops)¶ add a socket protocol handler
Parameters
const struct net_proto_family *ops
description of protocol
This function is called by a protocol handler that wants to advertise its address family, and have it linked into the socket interface. The value ops->family corresponds to the socket system call protocol family.
-
void
sock_unregister
(int family)¶ remove a protocol handler
Parameters
int family
protocol family to remove
This function is called by a protocol handler that wants to remove its address family, and have it unlinked from the new socket creation.
If protocol handler is a module, then it can use module reference counts to protect against new references. If protocol handler is not a module then it needs to provide its own protection in the ops->create routine.
-
int
kernel_bind
(struct socket *sock, struct sockaddr *addr, int addrlen)¶ bind an address to a socket (kernel space)
Parameters
struct socket *sock
socket
struct sockaddr *addr
address
int addrlen
length of address
Returns 0 or an error.
Parameters
struct socket *sock
socket
int backlog
pending connections queue size
Returns 0 or an error.
-
int
kernel_accept
(struct socket *sock, struct socket **newsock, int flags)¶ accept a connection (kernel space)
Parameters
struct socket *sock
listening socket
struct socket **newsock
new connected socket
int flags
flags
flags must be SOCK_CLOEXEC, SOCK_NONBLOCK or 0. If it fails, newsock is guaranteed to be
NULL
. Returns 0 or an error.
-
int
kernel_connect
(struct socket *sock, struct sockaddr *addr, int addrlen, int flags)¶ connect a socket (kernel space)
Parameters
struct socket *sock
socket
struct sockaddr *addr
address
int addrlen
address length
int flags
flags (O_NONBLOCK, …)
For datagram sockets, addr is the address to which datagrams are sent by default, and the only address from which datagrams are received. For stream sockets, attempts to connect to addr. Returns 0 or an error code.
-
int
kernel_getsockname
(struct socket *sock, struct sockaddr *addr)¶ get the address which the socket is bound (kernel space)
Parameters
struct socket *sock
socket
struct sockaddr *addr
address holder
Fills the addr pointer with the address which the socket is bound. Returns 0 or an error code.
-
int
kernel_getpeername
(struct socket *sock, struct sockaddr *addr)¶ get the address which the socket is connected (kernel space)
Parameters
struct socket *sock
socket
struct sockaddr *addr
address holder
Fills the addr pointer with the address which the socket is connected. Returns 0 or an error code.
-
int
kernel_sendpage
(struct socket *sock, struct page *page, int offset, size_t size, int flags)¶ send a
page
through a socket (kernel space)
Parameters
struct socket *sock
socket
struct page *page
page
int offset
page offset
size_t size
total size in bytes
int flags
flags (MSG_DONTWAIT, …)
Returns the total amount sent in bytes or an error.
-
int
kernel_sendpage_locked
(struct sock *sk, struct page *page, int offset, size_t size, int flags)¶ send a
page
through the locked sock (kernel space)
Parameters
struct sock *sk
sock
struct page *page
page
int offset
page offset
size_t size
total size in bytes
int flags
flags (MSG_DONTWAIT, …)
Returns the total amount sent in bytes or an error. Caller must hold sk.
-
int
kernel_sock_shutdown
(struct socket *sock, enum sock_shutdown_cmd how)¶ shut down part of a full-duplex connection (kernel space)
Parameters
struct socket *sock
socket
enum sock_shutdown_cmd how
connection part
Returns 0 or an error.
-
u32
kernel_sock_ip_overhead
(struct sock *sk)¶ returns the IP overhead imposed by a socket
Parameters
struct sock *sk
socket
This routine returns the IP overhead imposed by a socket i.e. the length of the underlying IP header, depending on whether this is an IPv4 or IPv6 socket and the length from IP options turned on at the socket. Assumes that the caller has a lock on the socket.
-
struct sk_buff *
build_skb_around
(struct sk_buff *skb, void *data, unsigned int frag_size)¶ build a network buffer around provided skb
Parameters
struct sk_buff *skb
sk_buff provide by caller, must be memset cleared
void *data
data buffer provided by caller
unsigned int frag_size
size of data, or 0 if head was kmalloced
-
struct sk_buff *
napi_build_skb
(void *data, unsigned int frag_size)¶ build a network buffer
Parameters
void *data
data buffer provided by caller
unsigned int frag_size
size of data, or 0 if head was kmalloced
Description
Version of __napi_build_skb() that takes care of skb->head_frag and skb->pfmemalloc when the data is a page or page fragment.
Returns a new sk_buff
on success, NULL
on allocation failure.
-
struct sk_buff *
__alloc_skb
(unsigned int size, gfp_t gfp_mask, int flags, int node)¶ allocate a network buffer
Parameters
unsigned int size
size to allocate
gfp_t gfp_mask
allocation mask
int flags
If SKB_ALLOC_FCLONE is set, allocate from fclone cache instead of head cache and allocate a cloned (child) skb. If SKB_ALLOC_RX is set, __GFP_MEMALLOC will be used for allocations in case the data is required for writeback
int node
numa node to allocate memory on
Allocate a new
sk_buff
. The returned buffer has no headroom and a tail room of at least size bytes. The object has a reference count of one. The return is the buffer. On a failure the return isNULL
.Buffers may only be allocated from interrupts using a gfp_mask of
GFP_ATOMIC
.
-
struct sk_buff *
__netdev_alloc_skb
(struct net_device *dev, unsigned int len, gfp_t gfp_mask)¶ allocate an skbuff for rx on a specific device
Parameters
struct net_device *dev
network device to receive on
unsigned int len
length to allocate
gfp_t gfp_mask
get_free_pages mask, passed to alloc_skb
Allocate a new
sk_buff
and assign it a usage count of one. The buffer has NET_SKB_PAD headroom built in. Users should allocate the headroom they think they need without accounting for the built in space. The built in space is used for optimisations.NULL
is returned if there is no free memory.
-
struct sk_buff *
__napi_alloc_skb
(struct napi_struct *napi, unsigned int len, gfp_t gfp_mask)¶ allocate skbuff for rx in a specific NAPI instance
Parameters
struct napi_struct *napi
napi instance this buffer was allocated for
unsigned int len
length to allocate
gfp_t gfp_mask
get_free_pages mask, passed to alloc_skb and alloc_pages
Allocate a new sk_buff for use in NAPI receive. This buffer will attempt to allocate the head from a special reserved region used only for NAPI Rx allocation. By doing this we can save several CPU cycles by avoiding having to disable and re-enable IRQs.
NULL
is returned if there is no free memory.
-
void
__kfree_skb
(struct sk_buff *skb)¶ private function
Parameters
struct sk_buff *skb
buffer
Free an sk_buff. Release anything attached to the buffer. Clean the state. This is an internal helper function. Users should always call kfree_skb
-
void
kfree_skb
(struct sk_buff *skb)¶ free an sk_buff
Parameters
struct sk_buff *skb
buffer to free
Drop a reference to the buffer and free it if the usage count has hit zero.
-
void
skb_tx_error
(struct sk_buff *skb)¶ report an sk_buff xmit error
Parameters
struct sk_buff *skb
buffer that triggered an error
Report xmit error if a device callback is tracking this skb. skb must be freed afterwards.
-
void
consume_skb
(struct sk_buff *skb)¶ free an skbuff
Parameters
struct sk_buff *skb
buffer to free
Drop a ref to the buffer and free it if the usage count has hit zero Functions identically to kfree_skb, but kfree_skb assumes that the frame is being dropped after a failure and notes that
-
struct sk_buff *
alloc_skb_for_msg
(struct sk_buff *first)¶ allocate sk_buff to wrap frag list forming a msg
Parameters
struct sk_buff *first
first sk_buff of the msg
-
struct sk_buff *
skb_morph
(struct sk_buff *dst, struct sk_buff *src)¶ morph one skb into another
Parameters
struct sk_buff *dst
the skb to receive the contents
struct sk_buff *src
the skb to supply the contents
This is identical to skb_clone except that the target skb is supplied by the user.
The target skb is returned upon exit.
Parameters
struct sk_buff *skb
the skb to modify
gfp_t gfp_mask
allocation priority
This must be called on skb with SKBFL_ZEROCOPY_ENABLE. It will copy all frags into kernel and drop the reference to userspace pages.
If this function is called from an interrupt gfp_mask() must be
GFP_ATOMIC
.Returns 0 on success or a negative error code on failure to allocate kernel memory to copy to.
Parameters
struct sk_buff *skb
buffer to clone
gfp_t gfp_mask
allocation priority
Duplicate an
sk_buff
. The new one is not owned by a socket. Both copies share the same packet data but not structure. The new buffer has a reference count of 1. If the allocation fails the function returnsNULL
otherwise the new buffer is returned.If this function is called from an interrupt gfp_mask() must be
GFP_ATOMIC
.
-
struct sk_buff *
skb_copy
(const struct sk_buff *skb, gfp_t gfp_mask)¶ create private copy of an sk_buff
Parameters
const struct sk_buff *skb
buffer to copy
gfp_t gfp_mask
allocation priority
Make a copy of both an
sk_buff
and its data. This is used when the caller wishes to modify the data and needs a private copy of the data to alter. ReturnsNULL
on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.As by-product this function converts non-linear
sk_buff
to linear one, so thatsk_buff
becomes completely private and caller is allowed to modify all the data of returned buffer. This means that this function is not recommended for use in circumstances when only header is going to be modified. Use pskb_copy() instead.
-
struct sk_buff *
__pskb_copy_fclone
(struct sk_buff *skb, int headroom, gfp_t gfp_mask, bool fclone)¶ create copy of an sk_buff with private head.
Parameters
struct sk_buff *skb
buffer to copy
int headroom
headroom of new skb
gfp_t gfp_mask
allocation priority
bool fclone
if true allocate the copy of the skb from the fclone cache instead of the head cache; it is recommended to set this to true for the cases where the copy will likely be cloned
Make a copy of both an
sk_buff
and part of its data, located in header. Fragmented data remain shared. This is used when the caller wishes to modify only header ofsk_buff
and needs private copy of the header to alter. ReturnsNULL
on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.
-
int
pskb_expand_head
(struct sk_buff *skb, int nhead, int ntail, gfp_t gfp_mask)¶ reallocate header of
sk_buff
Parameters
struct sk_buff *skb
buffer to reallocate
int nhead
room to add at head
int ntail
room to add at tail
gfp_t gfp_mask
allocation priority
Expands (or creates identical copy, if nhead and ntail are zero) header of skb.
sk_buff
itself is not changed.sk_buff
MUST have reference count of 1. Returns zero in the case of success or error, if expansion failed. In the last case,sk_buff
is not changed.All the pointers pointing into skb header may change and must be reloaded after call to this function.
-
struct sk_buff *
skb_expand_head
(struct sk_buff *skb, unsigned int headroom)¶ reallocate header of
sk_buff
Parameters
struct sk_buff *skb
buffer to reallocate
unsigned int headroom
needed headroom
Unlike skb_realloc_headroom, this one does not allocate a new skb if possible; copies skb->sk to new skb as needed and frees original skb in case of failures.
It expect increased headroom and generates warning otherwise.
-
struct sk_buff *
skb_copy_expand
(const struct sk_buff *skb, int newheadroom, int newtailroom, gfp_t gfp_mask)¶ copy and expand sk_buff
Parameters
const struct sk_buff *skb
buffer to copy
int newheadroom
new free bytes at head
int newtailroom
new free bytes at tail
gfp_t gfp_mask
allocation priority
Make a copy of both an
sk_buff
and its data and while doing so allocate additional space.This is used when the caller wishes to modify the data and needs a private copy of the data to alter as well as more space for new fields. Returns
NULL
on failure or the pointer to the buffer on success. The returned buffer has a reference count of 1.You must pass
GFP_ATOMIC
as the allocation priority if this function is called from an interrupt.
-
int
__skb_pad
(struct sk_buff *skb, int pad, bool free_on_error)¶ zero pad the tail of an skb
Parameters
struct sk_buff *skb
buffer to pad
int pad
space to pad
bool free_on_error
free buffer on error
Ensure that a buffer is followed by a padding area that is zero filled. Used by network drivers which may DMA or transfer data beyond the buffer end onto the wire.
May return error in out of memory cases. The skb is freed on error if free_on_error is true.
-
void *
pskb_put
(struct sk_buff *skb, struct sk_buff *tail, int len)¶ add data to the tail of a potentially fragmented buffer
Parameters
struct sk_buff *skb
start of the buffer to use
struct sk_buff *tail
tail fragment of the buffer to use
int len
amount of data to add
This function extends the used data area of the potentially fragmented buffer. tail must be the last fragment of skb – or skb itself. If this would exceed the total buffer size the kernel will panic. A pointer to the first byte of the extra data is returned.
-
void *
skb_put
(struct sk_buff *skb, unsigned int len)¶ add data to a buffer
Parameters
struct sk_buff *skb
buffer to use
unsigned int len
amount of data to add
This function extends the used data area of the buffer. If this would exceed the total buffer size the kernel will panic. A pointer to the first byte of the extra data is returned.
-
void *
skb_push
(struct sk_buff *skb, unsigned int len)¶ add data to the start of a buffer
Parameters
struct sk_buff *skb
buffer to use
unsigned int len
amount of data to add
This function extends the used data area of the buffer at the buffer start. If this would exceed the total buffer headroom the kernel will panic. A pointer to the first byte of the extra data is returned.
-
void *
skb_pull
(struct sk_buff *skb, unsigned int len)¶ remove data from the start of a buffer
Parameters
struct sk_buff *skb
buffer to use
unsigned int len
amount of data to remove
This function removes data from the start of a buffer, returning the memory to the headroom. A pointer to the next data in the buffer is returned. Once the data has been pulled future pushes will overwrite the old data.
-
void *
skb_pull_data
(struct sk_buff *skb, size_t len)¶ remove data from the start of a buffer returning its original position.
Parameters
struct sk_buff *skb
buffer to use
size_t len
amount of data to remove
This function removes data from the start of a buffer, returning the memory to the headroom. A pointer to the original data in the buffer is returned after checking if there is enough data to pull. Once the data has been pulled future pushes will overwrite the old data.
-
void
skb_trim
(struct sk_buff *skb, unsigned int len)¶ remove end from a buffer
Parameters
struct sk_buff *skb
buffer to alter
unsigned int len
new length
Cut the length of a buffer down by removing data from the tail. If the buffer is already under the length specified it is not modified. The skb must be linear.
-
void *
__pskb_pull_tail
(struct sk_buff *skb, int delta)¶ advance tail of skb header
Parameters
struct sk_buff *skb
buffer to reallocate
int delta
number of bytes to advance tail
The function makes a sense only on a fragmented
sk_buff
, it expands header moving its tail forward and copying necessary data from fragmented part.sk_buff
MUST have reference count of 1.Returns
NULL
(andsk_buff
does not change) if pull failed or value of new tail of skb in the case of success.All the pointers pointing into skb header may change and must be reloaded after call to this function.
-
int
skb_copy_bits
(const struct sk_buff *skb, int offset, void *to, int len)¶ copy bits from skb to kernel buffer
Parameters
const struct sk_buff *skb
source skb
int offset
offset in source
void *to
destination buffer
int len
number of bytes to copy
Copy the specified number of bytes from the source skb to the destination buffer.
- CAUTION ! :
If its prototype is ever changed, check arch/{*}/net/{*}.S files, since it is called from BPF assembly code.
-
int
skb_store_bits
(struct sk_buff *skb, int offset, const void *from, int len)¶ store bits from kernel buffer to skb
Parameters
struct sk_buff *skb
destination buffer
int offset
offset in destination
const void *from
source buffer
int len
number of bytes to copy
Copy the specified number of bytes from the source buffer to the destination skb. This function handles all the messy bits of traversing fragment lists and such.
-
int
skb_zerocopy
(struct sk_buff *to, struct sk_buff *from, int len, int hlen)¶ Zero copy skb to skb
Parameters
struct sk_buff *to
destination buffer
struct sk_buff *from
source buffer
int len
number of bytes to copy from source buffer
int hlen
size of linear headroom in destination buffer
Copies up to len bytes from from to to by creating references to the frags in the source buffer.
The hlen as calculated by skb_zerocopy_headlen() specifies the headroom in the to buffer.
Return value: 0: everything is OK -ENOMEM: couldn’t orphan frags of from due to lack of memory -EFAULT:
skb_copy_bits()
found some problem with skb geometry
-
struct sk_buff *
skb_dequeue
(struct sk_buff_head *list)¶ remove from the head of the queue
Parameters
struct sk_buff_head *list
list to dequeue from
Remove the head of the list. The list lock is taken so the function may be used safely with other locking list functions. The head item is returned or
NULL
if the list is empty.
-
struct sk_buff *
skb_dequeue_tail
(struct sk_buff_head *list)¶ remove from the tail of the queue
Parameters
struct sk_buff_head *list
list to dequeue from
Remove the tail of the list. The list lock is taken so the function may be used safely with other locking list functions. The tail item is returned or
NULL
if the list is empty.
-
void
skb_queue_purge
(struct sk_buff_head *list)¶ empty a list
Parameters
struct sk_buff_head *list
list to empty
Delete all buffers on an
sk_buff
list. Each buffer is removed from the list and one reference dropped. This function takes the list lock and is atomic with respect to other list locking functions.
-
void
skb_queue_head
(struct sk_buff_head *list, struct sk_buff *newsk)¶ queue a buffer at the list head
Parameters
struct sk_buff_head *list
list to use
struct sk_buff *newsk
buffer to queue
Queue a buffer at the start of the list. This function takes the list lock and can be used safely with other locking
sk_buff
functions safely.A buffer cannot be placed on two lists at the same time.
-
void
skb_queue_tail
(struct sk_buff_head *list, struct sk_buff *newsk)¶ queue a buffer at the list tail
Parameters
struct sk_buff_head *list
list to use
struct sk_buff *newsk
buffer to queue
Queue a buffer at the tail of the list. This function takes the list lock and can be used safely with other locking
sk_buff
functions safely.A buffer cannot be placed on two lists at the same time.
-
void
skb_unlink
(struct sk_buff *skb, struct sk_buff_head *list)¶ remove a buffer from a list
Parameters
struct sk_buff *skb
buffer to remove
struct sk_buff_head *list
list to use
Remove a packet from a list. The list locks are taken and this function is atomic with respect to other list locked calls
You must know what list the SKB is on.
-
void
skb_append
(struct sk_buff *old, struct sk_buff *newsk, struct sk_buff_head *list)¶ append a buffer
Parameters
struct sk_buff *old
buffer to insert after
struct sk_buff *newsk
buffer to insert
struct sk_buff_head *list
list to use
Place a packet after a given packet in a list. The list locks are taken and this function is atomic with respect to other list locked calls. A buffer cannot be placed on two lists at the same time.
-
void
skb_split
(struct sk_buff *skb, struct sk_buff *skb1, const u32 len)¶ Split fragmented skb to two parts at length len.
Parameters
struct sk_buff *skb
the buffer to split
struct sk_buff *skb1
the buffer to receive the second part
const u32 len
new length for skb
-
void
skb_prepare_seq_read
(struct sk_buff *skb, unsigned int from, unsigned int to, struct skb_seq_state *st)¶ Prepare a sequential read of skb data
Parameters
struct sk_buff *skb
the buffer to read
unsigned int from
lower offset of data to be read
unsigned int to
upper offset of data to be read
struct skb_seq_state *st
state variable
Description
Initializes the specified state variable. Must be called before
invoking skb_seq_read()
for the first time.
-
unsigned int
skb_seq_read
(unsigned int consumed, const u8 **data, struct skb_seq_state *st)¶ Sequentially read skb data
Parameters
unsigned int consumed
number of bytes consumed by the caller so far
const u8 **data
destination pointer for data to be returned
struct skb_seq_state *st
state variable
Description
Reads a block of skb data at consumed relative to the
lower offset specified to skb_prepare_seq_read()
. Assigns
the head of the data block to data and returns the length
of the block or 0 if the end of the skb data or the upper
offset has been reached.
The caller is not required to consume all of the data
returned, i.e. consumed is typically set to the number
of bytes already consumed and the next call to
skb_seq_read()
will return the remaining part of the block.
- Note 1: The size of each block of data returned can be arbitrary,
this limitation is the cost for zerocopy sequential reads of potentially non linear data.
- Note 2: Fragment lists within fragments are not implemented
at the moment, state->root_skb could be replaced with a stack for this purpose.
-
void
skb_abort_seq_read
(struct skb_seq_state *st)¶ Abort a sequential read of skb data
Parameters
struct skb_seq_state *st
state variable
Description
Must be called if skb_seq_read()
was not called until it
returned 0.
-
unsigned int
skb_find_text
(struct sk_buff *skb, unsigned int from, unsigned int to, struct ts_config *config)¶ Find a text pattern in skb data
Parameters
struct sk_buff *skb
the buffer to look in
unsigned int from
search offset
unsigned int to
search limit
struct ts_config *config
textsearch configuration
Description
Finds a pattern in the skb data according to the specified
textsearch configuration. Use textsearch_next()
to retrieve
subsequent occurrences of the pattern. Returns the offset
to the first occurrence or UINT_MAX if no match was found.
-
void *
skb_pull_rcsum
(struct sk_buff *skb, unsigned int len)¶ pull skb and update receive checksum
Parameters
struct sk_buff *skb
buffer to update
unsigned int len
length of data pulled
This function performs an skb_pull on the packet and updates the CHECKSUM_COMPLETE checksum. It should be used on receive path processing instead of skb_pull unless you know that the checksum difference is zero (e.g., a valid IP header) or you are setting ip_summed to CHECKSUM_NONE.
-
struct sk_buff *
skb_segment
(struct sk_buff *head_skb, netdev_features_t features)¶ Perform protocol segmentation on skb.
Parameters
struct sk_buff *head_skb
buffer to segment
netdev_features_t features
features for the output path (see dev->features)
This function performs segmentation on the given skb. It returns a pointer to the first in a list of new skbs for the segments. In case of error it returns ERR_PTR(err).
-
int
skb_to_sgvec
(struct sk_buff *skb, struct scatterlist *sg, int offset, int len)¶ Fill a scatter-gather list from a socket buffer
Parameters
struct sk_buff *skb
Socket buffer containing the buffers to be mapped
struct scatterlist *sg
The scatter-gather list to map into
int offset
The offset into the buffer’s contents to start mapping
int len
Length of buffer space to be mapped
Fill the specified scatter-gather list with mappings/pointers into a region of the buffer space attached to a socket buffer. Returns either the number of scatterlist items used, or -EMSGSIZE if the contents could not fit.
-
int
skb_cow_data
(struct sk_buff *skb, int tailbits, struct sk_buff **trailer)¶ Check that a socket buffer’s data buffers are writable
Parameters
struct sk_buff *skb
The socket buffer to check.
int tailbits
Amount of trailing space to be added
struct sk_buff **trailer
Returned pointer to the skb where the tailbits space begins
Make sure that the data buffers attached to a socket buffer are writable. If they are not, private copies are made of the data buffers and the socket buffer is set to use these instead.
If tailbits is given, make sure that there is space to write tailbits bytes of data beyond current end of socket buffer. trailer will be set to point to the skb in which this space begins.
The number of scatterlist elements required to completely map the COW’d and extended socket buffer will be returned.
-
struct sk_buff *
skb_clone_sk
(struct sk_buff *skb)¶ create clone of skb, and take reference to socket
Parameters
struct sk_buff *skb
the skb to clone
Description
This function creates a clone of a buffer that holds a reference on sk_refcnt. Buffers created via this function are meant to be returned using sock_queue_err_skb, or free via kfree_skb.
When passing buffers allocated with this function to sock_queue_err_skb it is necessary to wrap the call with sock_hold/sock_put in order to prevent the socket from being released prior to being enqueued on the sk_error_queue.
-
bool
skb_partial_csum_set
(struct sk_buff *skb, u16 start, u16 off)¶ set up and verify partial csum values for packet
Parameters
struct sk_buff *skb
the skb to set
u16 start
the number of bytes after skb->data to start checksumming.
u16 off
the offset from start to place the checksum.
Description
For untrusted partially-checksummed packets, we need to make sure the values for skb->csum_start and skb->csum_offset are valid so we don’t oops.
This function checks and sets those values and skb->ip_summed: if this returns false you should drop the packet.
-
int
skb_checksum_setup
(struct sk_buff *skb, bool recalculate)¶ set up partial checksum offset
Parameters
struct sk_buff *skb
the skb to set up
bool recalculate
if true the pseudo-header checksum will be recalculated
-
struct sk_buff *
skb_checksum_trimmed
(struct sk_buff *skb, unsigned int transport_len, __sum16(*skb_chkf)(struct sk_buff *skb))¶ validate checksum of an skb
Parameters
struct sk_buff *skb
the skb to check
unsigned int transport_len
the data length beyond the network header
__sum16(*skb_chkf)(struct sk_buff *skb)
checksum function to use
Description
Applies the given checksum function skb_chkf to the provided skb. Returns a checked and maybe trimmed skb. Returns NULL on error.
If the skb has data beyond the given transport length, then a trimmed & cloned skb is checked and returned.
Caller needs to set the skb transport header and free any returned skb if it differs from the provided skb.
-
bool
skb_try_coalesce
(struct sk_buff *to, struct sk_buff *from, bool *fragstolen, int *delta_truesize)¶ try to merge skb to prior one
Parameters
struct sk_buff *to
prior buffer
struct sk_buff *from
buffer to add
bool *fragstolen
pointer to boolean
int *delta_truesize
how much more was allocated than was requested
-
void
skb_scrub_packet
(struct sk_buff *skb, bool xnet)¶ scrub an skb
Parameters
struct sk_buff *skb
buffer to clean
bool xnet
packet is crossing netns
Description
skb_scrub_packet can be used after encapsulating or decapsulting a packet into/from a tunnel. Some information have to be cleared during these operations. skb_scrub_packet can also be used to clean a skb before injecting it in another namespace (xnet == true). We have to clear all information in the skb that could impact namespace isolation.
-
bool
skb_gso_validate_network_len
(const struct sk_buff *skb, unsigned int mtu)¶ Will a split GSO skb fit into a given MTU?
Parameters
const struct sk_buff *skb
GSO skb
unsigned int mtu
MTU to validate against
Description
skb_gso_validate_network_len validates if a given skb will fit a wanted MTU once split. It considers L3 headers, L4 headers, and the payload.
-
bool
skb_gso_validate_mac_len
(const struct sk_buff *skb, unsigned int len)¶ Will a split GSO skb fit in a given length?
Parameters
const struct sk_buff *skb
GSO skb
unsigned int len
length to validate against
Description
skb_gso_validate_mac_len validates if a given skb will fit a wanted length once split, including L2, L3 and L4 headers and the payload.
-
int
skb_eth_pop
(struct sk_buff *skb)¶ Drop the Ethernet header at the head of a packet
Parameters
struct sk_buff *skb
Socket buffer to modify
Description
Drop the Ethernet header of skb.
Expects that skb->data points to the mac header and that no VLAN tags are present.
Returns 0 on success, -errno otherwise.
-
int
skb_eth_push
(struct sk_buff *skb, const unsigned char *dst, const unsigned char *src)¶ Add a new Ethernet header at the head of a packet
Parameters
struct sk_buff *skb
Socket buffer to modify
const unsigned char *dst
Destination MAC address of the new header
const unsigned char *src
Source MAC address of the new header
Description
Prepend skb with a new Ethernet header.
Expects that skb->data points to the mac header, which must be empty.
Returns 0 on success, -errno otherwise.
-
int
skb_mpls_push
(struct sk_buff *skb, __be32 mpls_lse, __be16 mpls_proto, int mac_len, bool ethernet)¶ push a new MPLS header after mac_len bytes from start of the packet
Parameters
struct sk_buff *skb
buffer
__be32 mpls_lse
MPLS label stack entry to push
__be16 mpls_proto
ethertype of the new MPLS header (expects 0x8847 or 0x8848)
int mac_len
length of the MAC header
bool ethernet
flag to indicate if the resulting packet after skb_mpls_push is ethernet
Description
Expects skb->data at mac header.
Returns 0 on success, -errno otherwise.
-
int
skb_mpls_pop
(struct sk_buff *skb, __be16 next_proto, int mac_len, bool ethernet)¶ pop the outermost MPLS header
Parameters
struct sk_buff *skb
buffer
__be16 next_proto
ethertype of header after popped MPLS header
int mac_len
length of the MAC header
bool ethernet
flag to indicate if the packet is ethernet
Description
Expects skb->data at mac header.
Returns 0 on success, -errno otherwise.
-
int
skb_mpls_update_lse
(struct sk_buff *skb, __be32 mpls_lse)¶ modify outermost MPLS header and update csum
Parameters
struct sk_buff *skb
buffer
__be32 mpls_lse
new MPLS label stack entry to update to
Description
Expects skb->data at mac header.
Returns 0 on success, -errno otherwise.
-
int
skb_mpls_dec_ttl
(struct sk_buff *skb)¶ decrement the TTL of the outermost MPLS header
Parameters
struct sk_buff *skb
buffer
Description
Expects skb->data at mac header.
Returns 0 on success, -errno otherwise.
-
struct sk_buff *
alloc_skb_with_frags
(unsigned long header_len, unsigned long data_len, int max_page_order, int *errcode, gfp_t gfp_mask)¶ allocate skb with page frags
Parameters
unsigned long header_len
size of linear part
unsigned long data_len
needed length in frags
int max_page_order
max page order desired.
int *errcode
pointer to error code if any
gfp_t gfp_mask
allocation mask
Description
This can be used to allocate a paged skb, given a maximal order for frags.
-
void *
skb_ext_add
(struct sk_buff *skb, enum skb_ext_id id)¶ allocate space for given extension, COW if needed
Parameters
struct sk_buff *skb
buffer
enum skb_ext_id id
extension to allocate space for
Description
Allocates enough space for the given extension. If the extension is already present, a pointer to that extension is returned.
If the skb was cloned, COW applies and the returned memory can be modified without changing the extension space of clones buffers.
Returns pointer to the extension or NULL on allocation failure.
-
bool
sk_ns_capable
(const struct sock *sk, struct user_namespace *user_ns, int cap)¶ General socket capability test
Parameters
const struct sock *sk
Socket to use a capability on or through
struct user_namespace *user_ns
The user namespace of the capability to use
int cap
The capability to use
Description
Test to see if the opener of the socket had when the socket was created and the current process has the capability cap in the user namespace user_ns.
-
bool
sk_capable
(const struct sock *sk, int cap)¶ Socket global capability test
Parameters
const struct sock *sk
Socket to use a capability on or through
int cap
The global capability to use
Description
Test to see if the opener of the socket had when the socket was created and the current process has the capability cap in all user namespaces.
-
bool
sk_net_capable
(const struct sock *sk, int cap)¶ Network namespace socket capability test
Parameters
const struct sock *sk
Socket to use a capability on or through
int cap
The capability to use
Description
Test to see if the opener of the socket had when the socket was created and the current process has the capability cap over the network namespace the socket is a member of.
-
void
sk_set_memalloc
(struct sock *sk)¶ sets
SOCK_MEMALLOC
Parameters
struct sock *sk
socket to set it on
Description
Set SOCK_MEMALLOC
on a socket for access to emergency reserves.
It’s the responsibility of the admin to adjust min_free_kbytes
to meet the requirements
-
struct sock *
sk_alloc
(struct net *net, int family, gfp_t priority, struct proto *prot, int kern)¶ All socket objects are allocated here
Parameters
struct net *net
the applicable net namespace
int family
protocol family
gfp_t priority
for allocation (
GFP_KERNEL
,GFP_ATOMIC
, etc)struct proto *prot
struct proto associated with this new sock instance
int kern
is this to be a kernel socket?
-
struct sock *
sk_clone_lock
(const struct sock *sk, const gfp_t priority)¶ clone a socket, and lock its clone
Parameters
const struct sock *sk
the socket to clone
const gfp_t priority
for allocation (
GFP_KERNEL
,GFP_ATOMIC
, etc)Caller must unlock socket even in error path (bh_unlock_sock(newsk))
-
bool
skb_page_frag_refill
(unsigned int sz, struct page_frag *pfrag, gfp_t gfp)¶ check that a page_frag contains enough room
Parameters
unsigned int sz
minimum size of the fragment we want to get
struct page_frag *pfrag
pointer to page_frag
gfp_t gfp
priority for memory allocation
Note
While this allocator tries to use high order pages, there is no guarantee that allocations succeed. Therefore, sz MUST be less or equal than PAGE_SIZE.
-
int
sk_wait_data
(struct sock *sk, long *timeo, const struct sk_buff *skb)¶ wait for data to arrive at sk_receive_queue
Parameters
struct sock *sk
sock to wait on
long *timeo
for how long
const struct sk_buff *skb
last skb seen on sk_receive_queue
Description
Now socket state including sk->sk_err is changed only under lock, hence we may omit checks after joining wait queue. We check receive queue before schedule() only as optimization; it is very likely that release_sock() added new data.
-
int
__sk_mem_raise_allocated
(struct sock *sk, int size, int amt, int kind)¶ increase memory_allocated
Parameters
struct sock *sk
socket
int size
memory size to allocate
int amt
pages to allocate
int kind
allocation type
Similar to
__sk_mem_schedule()
, but does not update sk_forward_alloc
-
int
__sk_mem_schedule
(struct sock *sk, int size, int kind)¶ increase sk_forward_alloc and memory_allocated
Parameters
struct sock *sk
socket
int size
memory size to allocate
int kind
allocation type
If kind is SK_MEM_SEND, it means wmem allocation. Otherwise it means rmem allocation. This function assumes that protocols which have memory_pressure use sk_wmem_queued as write buffer accounting.
-
void
__sk_mem_reduce_allocated
(struct sock *sk, int amount)¶ reclaim memory_allocated
Parameters
struct sock *sk
socket
int amount
number of quanta
Similar to
__sk_mem_reclaim()
, but does not update sk_forward_alloc
-
void
__sk_mem_reclaim
(struct sock *sk, int amount)¶ reclaim sk_forward_alloc and memory_allocated
Parameters
struct sock *sk
socket
int amount
number of bytes (rounded down to a SK_MEM_QUANTUM multiple)
-
struct sk_buff *
__skb_try_recv_datagram
(struct sock *sk, struct sk_buff_head *queue, unsigned int flags, int *off, int *err, struct sk_buff **last)¶ Receive a datagram skbuff
Parameters
struct sock *sk
socket
struct sk_buff_head *queue
socket queue from which to receive
unsigned int flags
MSG_ flags
int *off
an offset in bytes to peek skb from. Returns an offset within an skb where data actually starts
int *err
error code returned
struct sk_buff **last
set to last peeked message to inform the wait function what to look for when peeking
Get a datagram skbuff, understands the peeking, nonblocking wakeups and possible races. This replaces identical code in packet, raw and udp, as well as the IPX AX.25 and Appletalk. It also finally fixes the long standing peek and read race for datagram sockets. If you alter this routine remember it must be re-entrant.
This function will lock the socket if a skb is returned, so the caller needs to unlock the socket in that case (usually by calling skb_free_datagram). Returns NULL with err set to -EAGAIN if no data was available or to some other value if an error was detected.
It does not lock socket since today. This function is
free of race conditions. This measure should/can improve
significantly datagram socket latencies at high loads,
when data copying to user space takes lots of time.
(BTW I’ve just killed the last cli() in IP/IPv6/core/netlink/packet
Great win.)
–ANK (980729)
The order of the tests when we find no data waiting are specified quite explicitly by POSIX 1003.1g, don’t change them without having the standard around please.
-
int
skb_kill_datagram
(struct sock *sk, struct sk_buff *skb, unsigned int flags)¶ Free a datagram skbuff forcibly
Parameters
struct sock *sk
socket
struct sk_buff *skb
datagram skbuff
unsigned int flags
MSG_ flags
This function frees a datagram skbuff that was received by skb_recv_datagram. The flags argument must match the one used for skb_recv_datagram.
If the MSG_PEEK flag is set, and the packet is still on the receive queue of the socket, it will be taken off the queue before it is freed.
This function currently only disables BH when acquiring the sk_receive_queue lock. Therefore it must not be used in a context where that lock is acquired in an IRQ context.
It returns 0 if the packet was removed by us.
-
int
skb_copy_and_hash_datagram_iter
(const struct sk_buff *skb, int offset, struct iov_iter *to, int len, struct ahash_request *hash)¶ Copy datagram to an iovec iterator and update a hash.
Parameters
const struct sk_buff *skb
buffer to copy
int offset
offset in the buffer to start copying from
struct iov_iter *to
iovec iterator to copy to
int len
amount of data to copy from buffer to iovec
struct ahash_request *hash
hash request to update
-
int
skb_copy_datagram_iter
(const struct sk_buff *skb, int offset, struct iov_iter *to, int len)¶ Copy a datagram to an iovec iterator.
Parameters
const struct sk_buff *skb
buffer to copy
int offset
offset in the buffer to start copying from
struct iov_iter *to
iovec iterator to copy to
int len
amount of data to copy from buffer to iovec
-
int
skb_copy_datagram_from_iter
(struct sk_buff *skb, int offset, struct iov_iter *from, int len)¶ Copy a datagram from an iov_iter.
Parameters
struct sk_buff *skb
buffer to copy
int offset
offset in the buffer to start copying to
struct iov_iter *from
the copy source
int len
amount of data to copy to buffer from iovec
Returns 0 or -EFAULT.
-
int
zerocopy_sg_from_iter
(struct sk_buff *skb, struct iov_iter *from)¶ Build a zerocopy datagram from an iov_iter
Parameters
struct sk_buff *skb
buffer to copy
struct iov_iter *from
the source to copy from
The function will first copy up to headlen, and then pin the userspace pages and build frags through them.
Returns 0, -EFAULT or -EMSGSIZE.
-
int
skb_copy_and_csum_datagram_msg
(struct sk_buff *skb, int hlen, struct msghdr *msg)¶ Copy and checksum skb to user iovec.
Parameters
struct sk_buff *skb
skbuff
int hlen
hardware length
struct msghdr *msg
destination
Caller _must_ check that skb will fit to this iovec.
Return
- 0 - success.
-EINVAL - checksum failure. -EFAULT - fault during copy.
-
__poll_t
datagram_poll
(struct file *file, struct socket *sock, poll_table *wait)¶ generic datagram poll
Parameters
struct file *file
file struct
struct socket *sock
socket
poll_table *wait
poll table
Datagram poll: Again totally generic. This also handles sequenced packet sockets providing the socket receive queue is only ever holding data ready to receive.
Note
- when you don’t use this routine for this protocol,
and you use a different write policy from sock_writeable() then please supply your own write_space callback.
-
int
sk_stream_wait_connect
(struct sock *sk, long *timeo_p)¶ Wait for a socket to get into the connected state
Parameters
struct sock *sk
sock to wait on
long *timeo_p
for how long to wait
Description
Must be called with the socket locked.
-
int
sk_stream_wait_memory
(struct sock *sk, long *timeo_p)¶ Wait for more memory for a socket
Parameters
struct sock *sk
socket to wait for memory
long *timeo_p
for how long
Socket Filter¶
-
int
sk_filter_trim_cap
(struct sock *sk, struct sk_buff *skb, unsigned int cap)¶ run a packet through a socket filter
Parameters
struct sock *sk
sock associated with
sk_buff
struct sk_buff *skb
buffer to filter
unsigned int cap
limit on how short the eBPF program may trim the packet
Description
Run the eBPF program and then cut skb->data to correct size returned by the program. If pkt_len is 0 we toss packet. If skb->len is smaller than pkt_len we keep whole skb->data. This is the socket level wrapper to bpf_prog_run. It returns 0 if the packet should be accepted or -EPERM if the packet should be tossed.
-
int
bpf_prog_create
(struct bpf_prog **pfp, struct sock_fprog_kern *fprog)¶ create an unattached filter
Parameters
struct bpf_prog **pfp
the unattached filter that is created
struct sock_fprog_kern *fprog
the filter program
Description
Create a filter independent of any socket. We first run some sanity checks on it to make sure it does not explode on us later. If an error occurs or there is insufficient memory for the filter a negative errno code is returned. On success the return is zero.
-
int
bpf_prog_create_from_user
(struct bpf_prog **pfp, struct sock_fprog *fprog, bpf_aux_classic_check_t trans, bool save_orig)¶ create an unattached filter from user buffer
Parameters
struct bpf_prog **pfp
the unattached filter that is created
struct sock_fprog *fprog
the filter program
bpf_aux_classic_check_t trans
post-classic verifier transformation handler
bool save_orig
save classic BPF program
Description
This function effectively does the same as bpf_prog_create()
, only
that it builds up its insns buffer from user space provided buffer.
It also allows for passing a bpf_aux_classic_check_t handler.
-
int
sk_attach_filter
(struct sock_fprog *fprog, struct sock *sk)¶ attach a socket filter
Parameters
struct sock_fprog *fprog
the filter program
struct sock *sk
the socket to use
Description
Attach the user’s filter code. We first run some sanity checks on it to make sure it does not explode on us later. If an error occurs or there is insufficient memory for the filter a negative errno code is returned. On success the return is zero.
Generic Network Statistics¶
-
struct
gnet_stats_basic
¶ byte/packet throughput statistics
Definition
struct gnet_stats_basic {
__u64 bytes;
__u32 packets;
};
Members
bytes
number of seen bytes
packets
number of seen packets
-
struct
gnet_stats_rate_est
¶ rate estimator
Definition
struct gnet_stats_rate_est {
__u32 bps;
__u32 pps;
};
Members
bps
current byte rate
pps
current packet rate
-
struct
gnet_stats_rate_est64
¶ rate estimator
Definition
struct gnet_stats_rate_est64 {
__u64 bps;
__u64 pps;
};
Members
bps
current byte rate
pps
current packet rate
-
struct
gnet_stats_queue
¶ queuing statistics
Definition
struct gnet_stats_queue {
__u32 qlen;
__u32 backlog;
__u32 drops;
__u32 requeues;
__u32 overlimits;
};
Members
qlen
queue length
backlog
backlog size of queue
drops
number of dropped packets
requeues
number of requeues
overlimits
number of enqueues over the limit
-
struct
gnet_estimator
¶ rate estimator configuration
Definition
struct gnet_estimator {
signed char interval;
unsigned char ewma_log;
};
Members
interval
sampling period
ewma_log
the log of measurement window weight
-
int
gnet_stats_start_copy_compat
(struct sk_buff *skb, int type, int tc_stats_type, int xstats_type, spinlock_t *lock, struct gnet_dump *d, int padattr)¶ start dumping procedure in compatibility mode
Parameters
struct sk_buff *skb
socket buffer to put statistics TLVs into
int type
TLV type for top level statistic TLV
int tc_stats_type
TLV type for backward compatibility struct tc_stats TLV
int xstats_type
TLV type for backward compatibility xstats TLV
spinlock_t *lock
statistics lock
struct gnet_dump *d
dumping handle
int padattr
padding attribute
Description
Initializes the dumping handle, grabs the statistic lock and appends an empty TLV header to the socket buffer for use a container for all other statistic TLVS.
The dumping handle is marked to be in backward compatibility mode telling all gnet_stats_copy_XXX() functions to fill a local copy of struct tc_stats.
Returns 0 on success or -1 if the room in the socket buffer was not sufficient.
-
int
gnet_stats_start_copy
(struct sk_buff *skb, int type, spinlock_t *lock, struct gnet_dump *d, int padattr)¶ start dumping procedure in compatibility mode
Parameters
struct sk_buff *skb
socket buffer to put statistics TLVs into
int type
TLV type for top level statistic TLV
spinlock_t *lock
statistics lock
struct gnet_dump *d
dumping handle
int padattr
padding attribute
Description
Initializes the dumping handle, grabs the statistic lock and appends an empty TLV header to the socket buffer for use a container for all other statistic TLVS.
Returns 0 on success or -1 if the room in the socket buffer was not sufficient.
-
int
gnet_stats_copy_basic
(struct gnet_dump *d, struct gnet_stats_basic_sync __percpu *cpu, struct gnet_stats_basic_sync *b, bool running)¶ copy basic statistics into statistic TLV
Parameters
struct gnet_dump *d
dumping handle
struct gnet_stats_basic_sync __percpu *cpu
copy statistic per cpu
struct gnet_stats_basic_sync *b
basic statistics
bool running
true if b represents a running qdisc, thus b’s internal values might change during basic reads. Only used if cpu is NULL
Context
task; must not be run from IRQ or BH contexts
Description
Appends the basic statistics to the top level TLV created by
gnet_stats_start_copy()
.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gnet_stats_copy_basic_hw
(struct gnet_dump *d, struct gnet_stats_basic_sync __percpu *cpu, struct gnet_stats_basic_sync *b, bool running)¶ copy basic hw statistics into statistic TLV
Parameters
struct gnet_dump *d
dumping handle
struct gnet_stats_basic_sync __percpu *cpu
copy statistic per cpu
struct gnet_stats_basic_sync *b
basic statistics
bool running
true if b represents a running qdisc, thus b’s internal values might change during basic reads. Only used if cpu is NULL
Context
task; must not be run from IRQ or BH contexts
Description
Appends the basic statistics to the top level TLV created by
gnet_stats_start_copy()
.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gnet_stats_copy_rate_est
(struct gnet_dump *d, struct net_rate_estimator __rcu **rate_est)¶ copy rate estimator statistics into statistics TLV
Parameters
struct gnet_dump *d
dumping handle
struct net_rate_estimator __rcu **rate_est
rate estimator
Description
Appends the rate estimator statistics to the top level TLV created by
gnet_stats_start_copy()
.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gnet_stats_copy_queue
(struct gnet_dump *d, struct gnet_stats_queue __percpu *cpu_q, struct gnet_stats_queue *q, __u32 qlen)¶ copy queue statistics into statistics TLV
Parameters
struct gnet_dump *d
dumping handle
struct gnet_stats_queue __percpu *cpu_q
per cpu queue statistics
struct gnet_stats_queue *q
queue statistics
__u32 qlen
queue length statistics
Description
Appends the queue statistics to the top level TLV created by
gnet_stats_start_copy()
. Using per cpu queue statistics if
they are available.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gnet_stats_copy_app
(struct gnet_dump *d, void *st, int len)¶ copy application specific statistics into statistics TLV
Parameters
struct gnet_dump *d
dumping handle
void *st
application specific statistics data
int len
length of data
Description
Appends the application specific statistics to the top level TLV created by
gnet_stats_start_copy()
and remembers the data for XSTATS if the dumping
handle is in backward compatibility mode.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gnet_stats_finish_copy
(struct gnet_dump *d)¶ finish dumping procedure
Parameters
struct gnet_dump *d
dumping handle
Description
Corrects the length of the top level TLV to include all TLVs added
by gnet_stats_copy_XXX() calls. Adds the backward compatibility TLVs
if gnet_stats_start_copy_compat()
was used and releases the statistics
lock.
Returns 0 on success or -1 with the statistic lock released if the room in the socket buffer was not sufficient.
-
int
gen_new_estimator
(struct gnet_stats_basic_sync *bstats, struct gnet_stats_basic_sync __percpu *cpu_bstats, struct net_rate_estimator __rcu **rate_est, spinlock_t *lock, bool running, struct nlattr *opt)¶ create a new rate estimator
Parameters
struct gnet_stats_basic_sync *bstats
basic statistics
struct gnet_stats_basic_sync __percpu *cpu_bstats
bstats per cpu
struct net_rate_estimator __rcu **rate_est
rate estimator statistics
spinlock_t *lock
lock for statistics and control path
bool running
true if bstats represents a running qdisc, thus bstats’ internal values might change during basic reads. Only used if bstats_cpu is NULL
struct nlattr *opt
rate estimator configuration TLV
Description
Creates a new rate estimator with bstats
as source and rate_est
as destination. A new timer with the interval specified in the
configuration TLV is created. Upon each interval, the latest statistics
will be read from bstats
and the estimated rate will be stored in
rate_est
with the statistics lock grabbed during this period.
Returns 0 on success or a negative error code.
-
void
gen_kill_estimator
(struct net_rate_estimator __rcu **rate_est)¶ remove a rate estimator
Parameters
struct net_rate_estimator __rcu **rate_est
rate estimator
Description
Removes the rate estimator.
-
int
gen_replace_estimator
(struct gnet_stats_basic_sync *bstats, struct gnet_stats_basic_sync __percpu *cpu_bstats, struct net_rate_estimator __rcu **rate_est, spinlock_t *lock, bool running, struct nlattr *opt)¶ replace rate estimator configuration
Parameters
struct gnet_stats_basic_sync *bstats
basic statistics
struct gnet_stats_basic_sync __percpu *cpu_bstats
bstats per cpu
struct net_rate_estimator __rcu **rate_est
rate estimator statistics
spinlock_t *lock
lock for statistics and control path
bool running
true if bstats represents a running qdisc, thus bstats’ internal values might change during basic reads. Only used if cpu_bstats is NULL
struct nlattr *opt
rate estimator configuration TLV
Description
Replaces the configuration of a rate estimator by calling
gen_kill_estimator()
and gen_new_estimator()
.
Returns 0 on success or a negative error code.
-
bool
gen_estimator_active
(struct net_rate_estimator __rcu **rate_est)¶ test if estimator is currently in use
Parameters
struct net_rate_estimator __rcu **rate_est
rate estimator
Description
Returns true if estimator is active, and false if not.
SUN RPC subsystem¶
-
__be32 *
xdr_encode_opaque_fixed
(__be32 *p, const void *ptr, unsigned int nbytes)¶ Encode fixed length opaque data
Parameters
__be32 *p
pointer to current position in XDR buffer.
const void *ptr
pointer to data to encode (or NULL)
unsigned int nbytes
size of data.
Description
Copy the array of data of length nbytes at ptr to the XDR buffer at position p, then align to the next 32-bit boundary by padding with zero bytes (see RFC1832). Returns the updated current XDR buffer position
Note
if ptr is NULL, only the padding is performed.
-
__be32 *
xdr_encode_opaque
(__be32 *p, const void *ptr, unsigned int nbytes)¶ Encode variable length opaque data
Parameters
__be32 *p
pointer to current position in XDR buffer.
const void *ptr
pointer to data to encode (or NULL)
unsigned int nbytes
size of data.
Description
Returns the updated current XDR buffer position
-
void
xdr_terminate_string
(const struct xdr_buf *buf, const u32 len)¶ ‘0’-terminate a string residing in an xdr_buf
Parameters
const struct xdr_buf *buf
XDR buffer where string resides
const u32 len
length of string, in bytes
-
void
xdr_inline_pages
(struct xdr_buf *xdr, unsigned int offset, struct page **pages, unsigned int base, unsigned int len)¶ Prepare receive buffer for a large reply
Parameters
struct xdr_buf *xdr
xdr_buf into which reply will be placed
unsigned int offset
expected offset where data payload will start, in bytes
struct page **pages
vector of struct page pointers
unsigned int base
offset in first page where receive should start, in bytes
unsigned int len
expected size of the upper layer data payload, in bytes
-
void
_copy_from_pages
(char *p, struct page **pages, size_t pgbase, size_t len)¶
Parameters
char *p
pointer to destination
struct page **pages
array of pages
size_t pgbase
offset of source data
size_t len
length
Description
Copies data into an arbitrary memory location from an array of pages The copy is assumed to be non-overlapping.
-
unsigned int
xdr_stream_pos
(const struct xdr_stream *xdr)¶ Return the current offset from the start of the xdr_stream
Parameters
const struct xdr_stream *xdr
pointer to struct xdr_stream
-
unsigned int
xdr_page_pos
(const struct xdr_stream *xdr)¶ Return the current offset from the start of the xdr pages
Parameters
const struct xdr_stream *xdr
pointer to struct xdr_stream
-
void
xdr_init_encode
(struct xdr_stream *xdr, struct xdr_buf *buf, __be32 *p, struct rpc_rqst *rqst)¶ Initialize a struct xdr_stream for sending data.
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
struct xdr_buf *buf
pointer to XDR buffer in which to encode data
__be32 *p
current pointer inside XDR buffer
struct rpc_rqst *rqst
pointer to controlling rpc_rqst, for debugging
Note
- at the moment the RPC client only passes the length of our
scratch buffer in the xdr_buf’s header kvec. Previously this meant we needed to call xdr_adjust_iovec() after encoding the data. With the new scheme, the xdr_stream manages the details of the buffer length, and takes care of adjusting the kvec length for us.
-
void
xdr_commit_encode
(struct xdr_stream *xdr)¶ Ensure all data is written to buffer
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
Description
We handle encoding across page boundaries by giving the caller a temporary location to write to, then later copying the data into place; xdr_commit_encode does that copying.
Normally the caller doesn’t need to call this directly, as the following xdr_reserve_space will do it. But an explicit call may be required at the end of encoding, or any other time when the xdr_buf data might be read.
-
__be32 *
xdr_reserve_space
(struct xdr_stream *xdr, size_t nbytes)¶ Reserve buffer space for sending
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
size_t nbytes
number of bytes to reserve
Description
Checks that we have enough buffer space to encode ‘nbytes’ more bytes of data. If so, update the total xdr_buf length, and adjust the length of the current kvec.
-
int
xdr_reserve_space_vec
(struct xdr_stream *xdr, struct kvec *vec, size_t nbytes)¶ Reserves a large amount of buffer space for sending
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
struct kvec *vec
pointer to a kvec array
size_t nbytes
number of bytes to reserve
Description
Reserves enough buffer space to encode ‘nbytes’ of data and stores the
pointers in ‘vec’. The size argument passed to xdr_reserve_space()
is
determined based on the number of bytes remaining in the current page to
avoid invalidating iov_base pointers when xdr_commit_encode()
is called.
-
void
xdr_truncate_encode
(struct xdr_stream *xdr, size_t len)¶ truncate an encode buffer
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
size_t len
new length of buffer
Description
Truncates the xdr stream, so that xdr->buf->len == len, and xdr->p points at offset len from the start of the buffer, and head, tail, and page lengths are adjusted to correspond.
If this means moving xdr->p to a different buffer, we assume that the end pointer should be set to the end of the current page, except in the case of the head buffer when we assume the head buffer’s current length represents the end of the available buffer.
This is not safe to use on a buffer that already has inlined page cache pages (as in a zero-copy server read reply), except for the simple case of truncating from one position in the tail to another.
-
int
xdr_restrict_buflen
(struct xdr_stream *xdr, int newbuflen)¶ decrease available buffer space
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
int newbuflen
new maximum number of bytes available
Description
Adjust our idea of how much space is available in the buffer. If we’ve already used too much space in the buffer, returns -1. If the available space is already smaller than newbuflen, returns 0 and does nothing. Otherwise, adjusts xdr->buf->buflen to newbuflen and ensures xdr->end is set at most offset newbuflen from the start of the buffer.
-
void
xdr_write_pages
(struct xdr_stream *xdr, struct page **pages, unsigned int base, unsigned int len)¶ Insert a list of pages into an XDR buffer for sending
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
struct page **pages
list of pages
unsigned int base
offset of first byte
unsigned int len
length of data in bytes
-
void
xdr_init_decode
(struct xdr_stream *xdr, struct xdr_buf *buf, __be32 *p, struct rpc_rqst *rqst)¶ Initialize an xdr_stream for decoding data.
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
struct xdr_buf *buf
pointer to XDR buffer from which to decode data
__be32 *p
current pointer inside XDR buffer
struct rpc_rqst *rqst
pointer to controlling rpc_rqst, for debugging
-
void
xdr_init_decode_pages
(struct xdr_stream *xdr, struct xdr_buf *buf, struct page **pages, unsigned int len)¶ Initialize an xdr_stream for decoding into pages
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
struct xdr_buf *buf
pointer to XDR buffer from which to decode data
struct page **pages
list of pages to decode into
unsigned int len
length in bytes of buffer in pages
-
__be32 *
xdr_inline_decode
(struct xdr_stream *xdr, size_t nbytes)¶ Retrieve XDR data to decode
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
size_t nbytes
number of bytes of data to decode
Description
Check if the input buffer is long enough to enable us to decode ‘nbytes’ more bytes of data starting at the current position. If so return the current pointer, then update the current pointer position.
-
unsigned int
xdr_read_pages
(struct xdr_stream *xdr, unsigned int len)¶ align page-based XDR data to current pointer position
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
unsigned int len
number of bytes of page data
Description
Moves data beyond the current pointer position from the XDR head[] buffer into the page list. Any data that lies beyond current position + len bytes is moved into the XDR tail[]. The xdr_stream current position is then advanced past that data to align to the next XDR object in the tail.
Returns the number of XDR encoded bytes now contained in the pages
-
void
xdr_enter_page
(struct xdr_stream *xdr, unsigned int len)¶ decode data from the XDR page
Parameters
struct xdr_stream *xdr
pointer to xdr_stream struct
unsigned int len
number of bytes of page data
Description
Moves data beyond the current pointer position from the XDR head[] buffer into the page list. Any data that lies beyond current position + “len” bytes is moved into the XDR tail[]. The current pointer is then repositioned at the beginning of the first XDR page.
-
int
xdr_buf_subsegment
(const struct xdr_buf *buf, struct xdr_buf *subbuf, unsigned int base, unsigned int len)¶ set subbuf to a portion of buf
Parameters
const struct xdr_buf *buf
an xdr buffer
struct xdr_buf *subbuf
the result buffer
unsigned int base
beginning of range in bytes
unsigned int len
length of range in bytes
Description
sets subbuf to an xdr buffer representing the portion of buf of length len starting at offset base.
buf and subbuf may be pointers to the same struct xdr_buf.
Returns -1 if base of length are out of bounds.
-
bool
xdr_stream_subsegment
(struct xdr_stream *xdr, struct xdr_buf *subbuf, unsigned int nbytes)¶ set subbuf to a portion of xdr
Parameters
struct xdr_stream *xdr
an xdr_stream set up for decoding
struct xdr_buf *subbuf
the result buffer
unsigned int nbytes
length of xdr to extract, in bytes
Description
Sets up subbuf to represent a portion of xdr. The portion starts at the current offset in xdr, and extends for a length of nbytes. If this is successful, xdr is advanced to the next position following that portion.
- Return values:
true
: subbuf has been initialized, and xdr has been advanced.false
: a bounds error has occurred
-
void
xdr_buf_trim
(struct xdr_buf *buf, unsigned int len)¶ lop at most “len” bytes off the end of “buf”
Parameters
struct xdr_buf *buf
buf to be trimmed
unsigned int len
number of bytes to reduce “buf” by
Description
Trim an xdr_buf by the given number of bytes by fixing up the lengths. Note that it’s possible that we’ll trim less than that amount if the xdr_buf is too small, or if (for instance) it’s all in the head and the parser has already read too far into it.
-
ssize_t
xdr_stream_decode_opaque
(struct xdr_stream *xdr, void *ptr, size_t size)¶ Decode variable length opaque
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
void *ptr
location to store opaque data
size_t size
size of storage buffer ptr
Description
- Return values:
On success, returns size of object stored in *ptr
-EBADMSG
on XDR buffer overflow-EMSGSIZE
on overflow of storage buffer ptr
-
ssize_t
xdr_stream_decode_opaque_dup
(struct xdr_stream *xdr, void **ptr, size_t maxlen, gfp_t gfp_flags)¶ Decode and duplicate variable length opaque
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
void **ptr
location to store pointer to opaque data
size_t maxlen
maximum acceptable object size
gfp_t gfp_flags
GFP mask to use
Description
- Return values:
On success, returns size of object stored in *ptr
-EBADMSG
on XDR buffer overflow-EMSGSIZE
if the size of the object would exceed maxlen-ENOMEM
on memory allocation failure
-
ssize_t
xdr_stream_decode_string
(struct xdr_stream *xdr, char *str, size_t size)¶ Decode variable length string
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
char *str
location to store string
size_t size
size of storage buffer str
Description
- Return values:
On success, returns length of NUL-terminated string stored in *str
-EBADMSG
on XDR buffer overflow-EMSGSIZE
on overflow of storage buffer str
-
ssize_t
xdr_stream_decode_string_dup
(struct xdr_stream *xdr, char **str, size_t maxlen, gfp_t gfp_flags)¶ Decode and duplicate variable length string
Parameters
struct xdr_stream *xdr
pointer to xdr_stream
char **str
location to store pointer to string
size_t maxlen
maximum acceptable string length
gfp_t gfp_flags
GFP mask to use
Description
- Return values:
On success, returns length of NUL-terminated string stored in *ptr
-EBADMSG
on XDR buffer overflow-EMSGSIZE
if the size of the string would exceed maxlen-ENOMEM
on memory allocation failure
-
void
svc_xprt_deferred_close
(struct svc_xprt *xprt)¶ Close a transport
Parameters
struct svc_xprt *xprt
transport instance
Description
Used in contexts that need to defer the work of shutting down the transport to an nfsd thread.
-
void
svc_xprt_received
(struct svc_xprt *xprt)¶ start next receiver thread
Parameters
struct svc_xprt *xprt
controlling transport
Description
The caller must hold the XPT_BUSY bit and must not thereafter touch transport data.
Note
XPT_DATA only gets cleared when a read-attempt finds no (or insufficient) data.
-
char *
svc_print_addr
(struct svc_rqst *rqstp, char *buf, size_t len)¶ Format rq_addr field for printing
Parameters
struct svc_rqst *rqstp
svc_rqst struct containing address to print
char *buf
target buffer for formatted address
size_t len
length of target buffer
-
void
svc_reserve
(struct svc_rqst *rqstp, int space)¶ change the space reserved for the reply to a request.
Parameters
struct svc_rqst *rqstp
The request in question
int space
new max space to reserve
Description
Each request reserves some space on the output queue of the transport to make sure the reply fits. This function reduces that reserved space to be the amount of space used already, plus space.
-
struct svc_xprt *
svc_find_xprt
(struct svc_serv *serv, const char *xcl_name, struct net *net, const sa_family_t af, const unsigned short port)¶ find an RPC transport instance
Parameters
struct svc_serv *serv
pointer to svc_serv to search
const char *xcl_name
C string containing transport’s class name
struct net *net
owner net pointer
const sa_family_t af
Address family of transport’s local address
const unsigned short port
transport’s IP port number
Description
Return the transport instance pointer for the endpoint accepting connections/peer traffic from the specified transport class, address family and port.
Specifying 0 for the address family or port is effectively a wild-card, and will result in matching the first transport in the service’s list that has a matching class name.
-
int
svc_xprt_names
(struct svc_serv *serv, char *buf, const int buflen)¶ format a buffer with a list of transport names
Parameters
struct svc_serv *serv
pointer to an RPC service
char *buf
pointer to a buffer to be filled in
const int buflen
length of buffer to be filled in
Description
Fills in buf with a string containing a list of transport names, each name terminated with ‘n’.
Returns positive length of the filled-in string on success; otherwise a negative errno value is returned if an error occurs.
-
int
xprt_register_transport
(struct xprt_class *transport)¶ register a transport implementation
Parameters
struct xprt_class *transport
transport to register
Description
If a transport implementation is loaded as a kernel module, it can call this interface to make itself known to the RPC client.
Return
0: transport successfully registered -EEXIST: transport already registered -EINVAL: transport module being unloaded
-
int
xprt_unregister_transport
(struct xprt_class *transport)¶ unregister a transport implementation
Parameters
struct xprt_class *transport
transport to unregister
Return
0: transport successfully unregistered -ENOENT: transport never registered
-
int
xprt_find_transport_ident
(const char *netid)¶ convert a netid into a transport identifier
Parameters
const char *netid
transport to load
Return
> 0: transport identifier -ENOENT: transport module not available
-
int
xprt_reserve_xprt
(struct rpc_xprt *xprt, struct rpc_task *task)¶ serialize write access to transports
Parameters
struct rpc_xprt *xprt
pointer to the target transport
struct rpc_task *task
task that is requesting access to the transport
Description
This prevents mixing the payload of separate requests, and prevents transport connects from colliding with writes. No congestion control is provided.
-
void
xprt_release_xprt
(struct rpc_xprt *xprt, struct rpc_task *task)¶ allow other requests to use a transport
Parameters
struct rpc_xprt *xprt
transport with other tasks potentially waiting
struct rpc_task *task
task that is releasing access to the transport
Description
Note that “task” can be NULL. No congestion control is provided.
-
void
xprt_release_xprt_cong
(struct rpc_xprt *xprt, struct rpc_task *task)¶ allow other requests to use a transport
Parameters
struct rpc_xprt *xprt
transport with other tasks potentially waiting
struct rpc_task *task
task that is releasing access to the transport
Description
Note that “task” can be NULL. Another task is awoken to use the transport if the transport’s congestion window allows it.
-
bool
xprt_request_get_cong
(struct rpc_xprt *xprt, struct rpc_rqst *req)¶ Request congestion control credits
Parameters
struct rpc_xprt *xprt
pointer to transport
struct rpc_rqst *req
pointer to RPC request
Description
Useful for transports that require congestion control.
-
void
xprt_release_rqst_cong
(struct rpc_task *task)¶ housekeeping when request is complete
Parameters
struct rpc_task *task
RPC request that recently completed
Description
Useful for transports that require congestion control.
-
void
xprt_adjust_cwnd
(struct rpc_xprt *xprt, struct rpc_task *task, int result)¶ adjust transport congestion window
Parameters
struct rpc_xprt *xprt
pointer to xprt
struct rpc_task *task
recently completed RPC request used to adjust window
int result
result code of completed RPC request
Description
The transport code maintains an estimate on the maximum number of out- standing RPC requests, using a smoothed version of the congestion avoidance implemented in 44BSD. This is basically the Van Jacobson congestion algorithm: If a retransmit occurs, the congestion window is halved; otherwise, it is incremented by 1/cwnd when
a reply is received and
a full number of requests are outstanding and
the congestion window hasn’t been updated recently.
-
void
xprt_wake_pending_tasks
(struct rpc_xprt *xprt, int status)¶ wake all tasks on a transport’s pending queue
Parameters
struct rpc_xprt *xprt
transport with waiting tasks
int status
result code to plant in each task before waking it
-
void
xprt_wait_for_buffer_space
(struct rpc_xprt *xprt)¶ wait for transport output buffer to clear
Parameters
struct rpc_xprt *xprt
transport
Description
Note that we only set the timer for the case of RPC_IS_SOFT(), since we don’t in general want to force a socket disconnection due to an incomplete RPC call transmission.
-
bool
xprt_write_space
(struct rpc_xprt *xprt)¶ wake the task waiting for transport output buffer space
Parameters
struct rpc_xprt *xprt
transport with waiting tasks
Description
Can be called in a soft IRQ context, so xprt_write_space never sleeps.
-
void
xprt_disconnect_done
(struct rpc_xprt *xprt)¶ mark a transport as disconnected
Parameters
struct rpc_xprt *xprt
transport to flag for disconnect
-
void
xprt_force_disconnect
(struct rpc_xprt *xprt)¶ force a transport to disconnect
Parameters
struct rpc_xprt *xprt
transport to disconnect
-
unsigned long
xprt_reconnect_delay
(const struct rpc_xprt *xprt)¶ compute the wait before scheduling a connect
Parameters
const struct rpc_xprt *xprt
transport instance
-
void
xprt_reconnect_backoff
(struct rpc_xprt *xprt, unsigned long init_to)¶ compute the new re-establish timeout
Parameters
struct rpc_xprt *xprt
transport instance
unsigned long init_to
initial reestablish timeout
-
struct rpc_rqst *
xprt_lookup_rqst
(struct rpc_xprt *xprt, __be32 xid)¶ find an RPC request corresponding to an XID
Parameters
struct rpc_xprt *xprt
transport on which the original request was transmitted
__be32 xid
RPC XID of incoming reply
Description
Caller holds xprt->queue_lock.
-
void
xprt_pin_rqst
(struct rpc_rqst *req)¶ Pin a request on the transport receive list
Parameters
struct rpc_rqst *req
Request to pin
Description
Caller must ensure this is atomic with the call to xprt_lookup_rqst()
so should be holding xprt->queue_lock.
-
void
xprt_unpin_rqst
(struct rpc_rqst *req)¶ Unpin a request on the transport receive list
Parameters
struct rpc_rqst *req
Request to pin
Description
Caller should be holding xprt->queue_lock.
-
void
xprt_update_rtt
(struct rpc_task *task)¶ Update RPC RTT statistics
Parameters
struct rpc_task *task
RPC request that recently completed
Description
Caller holds xprt->queue_lock.
-
void
xprt_complete_rqst
(struct rpc_task *task, int copied)¶ called when reply processing is complete
Parameters
struct rpc_task *task
RPC request that recently completed
int copied
actual number of bytes received from the transport
Description
Caller holds xprt->queue_lock.
-
void
xprt_wait_for_reply_request_def
(struct rpc_task *task)¶ wait for reply
Parameters
struct rpc_task *task
pointer to rpc_task
Description
Set a request’s retransmit timeout based on the transport’s default timeout parameters. Used by transports that don’t adjust the retransmit timeout based on round-trip time estimation, and put the task to sleep on the pending queue.
-
void
xprt_wait_for_reply_request_rtt
(struct rpc_task *task)¶ wait for reply using RTT estimator
Parameters
struct rpc_task *task
pointer to rpc_task
Description
Set a request’s retransmit timeout using the RTT estimator, and put the task to sleep on the pending queue.
-
struct rpc_xprt *
xprt_get
(struct rpc_xprt *xprt)¶ return a reference to an RPC transport.
Parameters
struct rpc_xprt *xprt
pointer to the transport
-
void
xprt_put
(struct rpc_xprt *xprt)¶ release a reference to an RPC transport.
Parameters
struct rpc_xprt *xprt
pointer to the transport
-
void
rpc_wake_up
(struct rpc_wait_queue *queue)¶ wake up all rpc_tasks
Parameters
struct rpc_wait_queue *queue
rpc_wait_queue on which the tasks are sleeping
Description
Grabs queue->lock
-
void
rpc_wake_up_status
(struct rpc_wait_queue *queue, int status)¶ wake up all rpc_tasks and set their status value.
Parameters
struct rpc_wait_queue *queue
rpc_wait_queue on which the tasks are sleeping
int status
status value to set
Description
Grabs queue->lock
-
int
rpc_malloc
(struct rpc_task *task)¶ allocate RPC buffer resources
Parameters
struct rpc_task *task
RPC task
Description
A single memory region is allocated, which is split between the RPC call and RPC reply that this task is being used for. When this RPC is retired, the memory is released by calling rpc_free.
To prevent rpciod from hanging, this allocator never sleeps, returning -ENOMEM and suppressing warning if the request cannot be serviced immediately. The caller can arrange to sleep in a way that is safe for rpciod.
Most requests are ‘small’ (under 2KiB) and can be serviced from a mempool, ensuring that NFS reads and writes can always proceed, and that there is good locality of reference for these buffers.
-
void
rpc_free
(struct rpc_task *task)¶ free RPC buffer resources allocated via rpc_malloc
Parameters
struct rpc_task *task
RPC task
-
int
csum_partial_copy_to_xdr
(struct xdr_buf *xdr, struct sk_buff *skb)¶ checksum and copy data
Parameters
struct xdr_buf *xdr
target XDR buffer
struct sk_buff *skb
source skb
Description
We have set things up such that we perform the checksum of the UDP packet in parallel with the copies into the RPC client iovec. -DaveM
-
struct rpc_iostats *
rpc_alloc_iostats
(struct rpc_clnt *clnt)¶ allocate an rpc_iostats structure
Parameters
struct rpc_clnt *clnt
RPC program, version, and xprt
-
void
rpc_free_iostats
(struct rpc_iostats *stats)¶ release an rpc_iostats structure
Parameters
struct rpc_iostats *stats
doomed rpc_iostats structure
-
void
rpc_count_iostats_metrics
(const struct rpc_task *task, struct rpc_iostats *op_metrics)¶ tally up per-task stats
Parameters
const struct rpc_task *task
completed rpc_task
struct rpc_iostats *op_metrics
stat structure for OP that will accumulate stats from task
-
void
rpc_count_iostats
(const struct rpc_task *task, struct rpc_iostats *stats)¶ tally up per-task stats
Parameters
const struct rpc_task *task
completed rpc_task
struct rpc_iostats *stats
array of stat structures
Description
Uses the statidx from task
-
int
rpc_queue_upcall
(struct rpc_pipe *pipe, struct rpc_pipe_msg *msg)¶ queue an upcall message to userspace
Parameters
struct rpc_pipe *pipe
upcall pipe on which to queue given message
struct rpc_pipe_msg *msg
message to queue
Description
Call with an inode created by rpc_mkpipe() to queue an upcall. A userspace process may then later read the upcall by performing a read on an open file for this inode. It is up to the caller to initialize the fields of msg (other than msg->list) appropriately.
-
struct dentry *
rpc_mkpipe_dentry
(struct dentry *parent, const char *name, void *private, struct rpc_pipe *pipe)¶ make an rpc_pipefs file for kernel<->userspace communication
Parameters
struct dentry *parent
dentry of directory to create new “pipe” in
const char *name
name of pipe
void *private
private data to associate with the pipe, for the caller’s use
struct rpc_pipe *pipe
rpc_pipe
containing input parameters
Description
Data is made available for userspace to read by calls to
rpc_queue_upcall()
. The actual reads will result in calls to
ops->upcall, which will be called with the file pointer,
message, and userspace buffer to copy to.
Writes can come at any time, and do not necessarily have to be responses to upcalls. They will result in calls to msg->downcall.
The private argument passed here will be available to all these methods from the file pointer, via RPC_I(file_inode(file))->private.
-
int
rpc_unlink
(struct dentry *dentry)¶ remove a pipe
Parameters
struct dentry *dentry
dentry for the pipe, as returned from rpc_mkpipe
Description
After this call, lookups will no longer find the pipe, and any attempts to read or write using preexisting opens of the pipe will return -EPIPE.
-
void
rpc_init_pipe_dir_head
(struct rpc_pipe_dir_head *pdh)¶ initialise a struct rpc_pipe_dir_head
Parameters
struct rpc_pipe_dir_head *pdh
pointer to struct rpc_pipe_dir_head
-
void
rpc_init_pipe_dir_object
(struct rpc_pipe_dir_object *pdo, const struct rpc_pipe_dir_object_ops *pdo_ops, void *pdo_data)¶ initialise a struct rpc_pipe_dir_object
Parameters
struct rpc_pipe_dir_object *pdo
pointer to struct rpc_pipe_dir_object
const struct rpc_pipe_dir_object_ops *pdo_ops
pointer to const struct rpc_pipe_dir_object_ops
void *pdo_data
pointer to caller-defined data
-
int
rpc_add_pipe_dir_object
(struct net *net, struct rpc_pipe_dir_head *pdh, struct rpc_pipe_dir_object *pdo)¶ associate a rpc_pipe_dir_object to a directory
Parameters
struct net *net
pointer to struct net
struct rpc_pipe_dir_head *pdh
pointer to struct rpc_pipe_dir_head
struct rpc_pipe_dir_object *pdo
pointer to struct rpc_pipe_dir_object
-
void
rpc_remove_pipe_dir_object
(struct net *net, struct rpc_pipe_dir_head *pdh, struct rpc_pipe_dir_object *pdo)¶ remove a rpc_pipe_dir_object from a directory
Parameters
struct net *net
pointer to struct net
struct rpc_pipe_dir_head *pdh
pointer to struct rpc_pipe_dir_head
struct rpc_pipe_dir_object *pdo
pointer to struct rpc_pipe_dir_object
-
struct rpc_pipe_dir_object *
rpc_find_or_alloc_pipe_dir_object
(struct net *net, struct rpc_pipe_dir_head *pdh, int (*match)(struct rpc_pipe_dir_object *, void *), struct rpc_pipe_dir_object *(*alloc)(void *), void *data)¶
Parameters
struct net *net
pointer to struct net
struct rpc_pipe_dir_head *pdh
pointer to struct rpc_pipe_dir_head
int (*match)(struct rpc_pipe_dir_object *, void *)
match struct rpc_pipe_dir_object to data
struct rpc_pipe_dir_object *(*alloc)(void *)
allocate a new struct rpc_pipe_dir_object
void *data
user defined data for match() and alloc()
-
void
rpcb_getport_async
(struct rpc_task *task)¶ obtain the port for a given RPC service on a given host
Parameters
struct rpc_task *task
task that is waiting for portmapper request
Description
This one can be called for an ongoing RPC request, and can be used in an async (rpciod) context.
-
struct rpc_clnt *
rpc_create
(struct rpc_create_args *args)¶ create an RPC client and transport with one call
Parameters
struct rpc_create_args *args
rpc_clnt create argument structure
Description
Creates and initializes an RPC transport and an RPC client.
It can ping the server in order to determine if it is up, and to see if it supports this program and version. RPC_CLNT_CREATE_NOPING disables this behavior so asynchronous tasks can also use rpc_create.
-
struct rpc_clnt *
rpc_clone_client
(struct rpc_clnt *clnt)¶ Clone an RPC client structure
Parameters
struct rpc_clnt *clnt
RPC client whose parameters are copied
Description
Returns a fresh RPC client or an ERR_PTR.
-
struct rpc_clnt *
rpc_clone_client_set_auth
(struct rpc_clnt *clnt, rpc_authflavor_t flavor)¶ Clone an RPC client structure and set its auth
Parameters
struct rpc_clnt *clnt
RPC client whose parameters are copied
rpc_authflavor_t flavor
security flavor for new client
Description
Returns a fresh RPC client or an ERR_PTR.
-
int
rpc_switch_client_transport
(struct rpc_clnt *clnt, struct xprt_create *args, const struct rpc_timeout *timeout)¶ switch the RPC transport on the fly
Parameters
struct rpc_clnt *clnt
pointer to a struct rpc_clnt
struct xprt_create *args
pointer to the new transport arguments
const struct rpc_timeout *timeout
pointer to the new timeout parameters
Description
This function allows the caller to switch the RPC transport for the rpc_clnt structure ‘clnt’ to allow it to connect to a mirrored NFS server, for instance. It assumes that the caller has ensured that there are no active RPC tasks by using some form of locking.
Returns zero if “clnt” is now using the new xprt. Otherwise a negative errno is returned, and “clnt” continues to use the old xprt.
-
int
rpc_clnt_iterate_for_each_xprt
(struct rpc_clnt *clnt, int (*fn)(struct rpc_clnt *, struct rpc_xprt *, void *), void *data)¶ Apply a function to all transports
Parameters
struct rpc_clnt *clnt
pointer to client
int (*fn)(struct rpc_clnt *, struct rpc_xprt *, void *)
function to apply
void *data
void pointer to function data
Description
Iterates through the list of RPC transports currently attached to the client and applies the function fn(clnt, xprt, data).
On error, the iteration stops, and the function returns the error value.
-
struct rpc_clnt *
rpc_bind_new_program
(struct rpc_clnt *old, const struct rpc_program *program, u32 vers)¶ bind a new RPC program to an existing client
Parameters
struct rpc_clnt *old
old rpc_client
const struct rpc_program *program
rpc program to set
u32 vers
rpc program version
Description
Clones the rpc client and sets up a new RPC program. This is mainly of use for enabling different RPC programs to share the same transport. The Sun NFSv2/v3 ACL protocol can do this.
-
struct rpc_task *
rpc_run_task
(const struct rpc_task_setup *task_setup_data)¶ Allocate a new RPC task, then run rpc_execute against it
Parameters
const struct rpc_task_setup *task_setup_data
pointer to task initialisation data
-
int
rpc_call_sync
(struct rpc_clnt *clnt, const struct rpc_message *msg, int flags)¶ Perform a synchronous RPC call
Parameters
struct rpc_clnt *clnt
pointer to RPC client
const struct rpc_message *msg
RPC call parameters
int flags
RPC call flags
-
int
rpc_call_async
(struct rpc_clnt *clnt, const struct rpc_message *msg, int flags, const struct rpc_call_ops *tk_ops, void *data)¶ Perform an asynchronous RPC call
Parameters
struct rpc_clnt *clnt
pointer to RPC client
const struct rpc_message *msg
RPC call parameters
int flags
RPC call flags
const struct rpc_call_ops *tk_ops
RPC call ops
void *data
user call data
-
void
rpc_prepare_reply_pages
(struct rpc_rqst *req, struct page **pages, unsigned int base, unsigned int len, unsigned int hdrsize)¶ Prepare to receive a reply data payload into pages
Parameters
struct rpc_rqst *req
RPC request to prepare
struct page **pages
vector of struct page pointers
unsigned int base
offset in first page where receive should start, in bytes
unsigned int len
expected size of the upper layer data payload, in bytes
unsigned int hdrsize
expected size of upper layer reply header, in XDR words
-
size_t
rpc_peeraddr
(struct rpc_clnt *clnt, struct sockaddr *buf, size_t bufsize)¶ extract remote peer address from clnt’s xprt
Parameters
struct rpc_clnt *clnt
RPC client structure
struct sockaddr *buf
target buffer
size_t bufsize
length of target buffer
Description
Returns the number of bytes that are actually in the stored address.
-
const char *
rpc_peeraddr2str
(struct rpc_clnt *clnt, enum rpc_display_format_t format)¶ return remote peer address in printable format
Parameters
struct rpc_clnt *clnt
RPC client structure
enum rpc_display_format_t format
address format
Description
NB: the lifetime of the memory referenced by the returned pointer is the same as the rpc_xprt itself. As long as the caller uses this pointer, it must hold the RCU read lock.
-
int
rpc_localaddr
(struct rpc_clnt *clnt, struct sockaddr *buf, size_t buflen)¶ discover local endpoint address for an RPC client
Parameters
struct rpc_clnt *clnt
RPC client structure
struct sockaddr *buf
target buffer
size_t buflen
size of target buffer, in bytes
Description
Returns zero and fills in “buf” and “buflen” if successful; otherwise, a negative errno is returned.
This works even if the underlying transport is not currently connected, or if the upper layer never previously provided a source address.
The result of this function call is transient: multiple calls in succession may give different results, depending on how local networking configuration changes over time.
-
struct net *
rpc_net_ns
(struct rpc_clnt *clnt)¶ Get the network namespace for this RPC client
Parameters
struct rpc_clnt *clnt
RPC client to query
-
size_t
rpc_max_payload
(struct rpc_clnt *clnt)¶ Get maximum payload size for a transport, in bytes
Parameters
struct rpc_clnt *clnt
RPC client to query
Description
For stream transports, this is one RPC record fragment (see RFC 1831), as we don’t support multi-record requests yet. For datagram transports, this is the size of an IP packet minus the IP, UDP, and RPC header sizes.
-
size_t
rpc_max_bc_payload
(struct rpc_clnt *clnt)¶ Get maximum backchannel payload size, in bytes
Parameters
struct rpc_clnt *clnt
RPC client to query
-
void
rpc_force_rebind
(struct rpc_clnt *clnt)¶ force transport to check that remote port is unchanged
Parameters
struct rpc_clnt *clnt
client to rebind
-
int
rpc_clnt_test_and_add_xprt
(struct rpc_clnt *clnt, struct rpc_xprt_switch *xps, struct rpc_xprt *xprt, void *dummy)¶ Test and add a new transport to a rpc_clnt
Parameters
struct rpc_clnt *clnt
pointer to struct rpc_clnt
struct rpc_xprt_switch *xps
pointer to struct rpc_xprt_switch,
struct rpc_xprt *xprt
pointer struct rpc_xprt
void *dummy
unused
-
int
rpc_clnt_setup_test_and_add_xprt
(struct rpc_clnt *clnt, struct rpc_xprt_switch *xps, struct rpc_xprt *xprt, void *data)¶
Parameters
struct rpc_clnt *clnt
struct rpc_clnt to get the new transport
struct rpc_xprt_switch *xps
the rpc_xprt_switch to hold the new transport
struct rpc_xprt *xprt
the rpc_xprt to test
void *data
a struct rpc_add_xprt_test pointer that holds the test function and test function call data
Description
- This is an rpc_clnt_add_xprt setup() function which returns 1 so:
1) caller of the test function must dereference the rpc_xprt_switch and the rpc_xprt. 2) test function must call rpc_xprt_switch_add_xprt, usually in the rpc_call_done routine.
Upon success (return of 1), the test function adds the new transport to the rpc_clnt xprt switch
-
int
rpc_clnt_add_xprt
(struct rpc_clnt *clnt, struct xprt_create *xprtargs, int (*setup)(struct rpc_clnt *, struct rpc_xprt_switch *, struct rpc_xprt *, void *), void *data)¶ Add a new transport to a rpc_clnt
Parameters
struct rpc_clnt *clnt
pointer to struct rpc_clnt
struct xprt_create *xprtargs
pointer to struct xprt_create
int (*setup)(struct rpc_clnt *, struct rpc_xprt_switch *, struct rpc_xprt *, void *)
callback to test and/or set up the connection
void *data
pointer to setup function data
Description
Creates a new transport using the parameters set in args and adds it to clnt. If ping is set, then test that connectivity succeeds before adding the new transport.
Network device support¶
Driver Support¶
-
void
dev_add_pack
(struct packet_type *pt)¶ add packet handler
Parameters
struct packet_type *pt
packet type declaration
Add a protocol handler to the networking stack. The passed
packet_type
is linked into kernel lists and may not be freed until it has been removed from the kernel lists.This call does not sleep therefore it can not guarantee all CPU’s that are in middle of receiving packets will see the new packet type (until the next received packet).
-
void
__dev_remove_pack
(struct packet_type *pt)¶ remove packet handler
Parameters
struct packet_type *pt
packet type declaration
Remove a protocol handler that was previously added to the kernel protocol handlers by
dev_add_pack()
. The passedpacket_type
is removed from the kernel lists and can be freed or reused once this function returns.The packet type might still be in use by receivers and must not be freed until after all the CPU’s have gone through a quiescent state.
-
void
dev_remove_pack
(struct packet_type *pt)¶ remove packet handler
Parameters
struct packet_type *pt
packet type declaration
Remove a protocol handler that was previously added to the kernel protocol handlers by
dev_add_pack()
. The passedpacket_type
is removed from the kernel lists and can be freed or reused once this function returns.This call sleeps to guarantee that no CPU is looking at the packet type after return.
-
int
dev_get_iflink
(const struct net_device *dev)¶ get ‘iflink’ value of a interface
Parameters
const struct net_device *dev
targeted interface
Indicates the ifindex the interface is linked to. Physical interfaces have the same ‘ifindex’ and ‘iflink’ values.
-
int
dev_fill_metadata_dst
(struct net_device *dev, struct sk_buff *skb)¶ Retrieve tunnel egress information.
Parameters
struct net_device *dev
targeted interface
struct sk_buff *skb
The packet.
For better visibility of tunnel traffic OVS needs to retrieve egress tunnel information for a packet. Following API allows user to get this info.
-
struct net_device *
__dev_get_by_name
(struct net *net, const char *name)¶ find a device by its name
Parameters
struct net *net
the applicable net namespace
const char *name
name to find
Find an interface by name. Must be called under RTNL semaphore or dev_base_lock. If the name is found a pointer to the device is returned. If the name is not found then
NULL
is returned. The reference counters are not incremented so the caller must be careful with locks.
-
struct net_device *
dev_get_by_name_rcu
(struct net *net, const char *name)¶ find a device by its name
Parameters
struct net *net
the applicable net namespace
const char *name
name to find
Description
Find an interface by name.
If the name is found a pointer to the device is returned.
If the name is not found then NULL
is returned.
The reference counters are not incremented so the caller must be
careful with locks. The caller must hold RCU lock.
-
struct net_device *
dev_get_by_name
(struct net *net, const char *name)¶ find a device by its name
Parameters
struct net *net
the applicable net namespace
const char *name
name to find
Find an interface by name. This can be called from any context and does its own locking. The returned handle has the usage count incremented and the caller must use dev_put() to release it when it is no longer needed.
NULL
is returned if no matching device is found.
-
struct net_device *
__dev_get_by_index
(struct net *net, int ifindex)¶ find a device by its ifindex
Parameters
struct net *net
the applicable net namespace
int ifindex
index of device
Search for an interface by index. Returns
NULL
if the device is not found or a pointer to the device. The device has not had its reference counter increased so the caller must be careful about locking. The caller must hold either the RTNL semaphore or dev_base_lock.
-
struct net_device *
dev_get_by_index_rcu
(struct net *net, int ifindex)¶ find a device by its ifindex
Parameters
struct net *net
the applicable net namespace
int ifindex
index of device
Search for an interface by index. Returns
NULL
if the device is not found or a pointer to the device. The device has not had its reference counter increased so the caller must be careful about locking. The caller must hold RCU lock.
-
struct net_device *
dev_get_by_index
(struct net *net, int ifindex)¶ find a device by its ifindex
Parameters
struct net *net
the applicable net namespace
int ifindex
index of device
Search for an interface by index. Returns NULL if the device is not found or a pointer to the device. The device returned has had a reference added and the pointer is safe until the user calls dev_put to indicate they have finished with it.
-
struct net_device *
dev_get_by_napi_id
(unsigned int napi_id)¶ find a device by napi_id
Parameters
unsigned int napi_id
ID of the NAPI struct
Search for an interface by NAPI ID. Returns
NULL
if the device is not found or a pointer to the device. The device has not had its reference counter increased so the caller must be careful about locking. The caller must hold RCU lock.
-
struct net_device *
dev_getbyhwaddr_rcu
(struct net *net, unsigned short type, const char *ha)¶ find a device by its hardware address
Parameters
struct net *net
the applicable net namespace
unsigned short type
media type of device
const char *ha
hardware address
Search for an interface by MAC address. Returns NULL if the device is not found or a pointer to the device. The caller must hold RCU or RTNL. The returned device has not had its ref count increased and the caller must therefore be careful about locking
-
struct net_device *
__dev_get_by_flags
(struct net *net, unsigned short if_flags, unsigned short mask)¶ find any device with given flags
Parameters
struct net *net
the applicable net namespace
unsigned short if_flags
IFF_* values
unsigned short mask
bitmask of bits in if_flags to check
Search for any interface with the given flags. Returns NULL if a device is not found or a pointer to the device. Must be called inside rtnl_lock(), and result refcount is unchanged.
-
bool
dev_valid_name
(const char *name)¶ check if name is okay for network device
Parameters
const char *name
name string
Network device names need to be valid file names to allow sysfs to work. We also disallow any kind of whitespace.
-
int
dev_alloc_name
(struct net_device *dev, const char *name)¶ allocate a name for a device
Parameters
struct net_device *dev
device
const char *name
name format string
Passed a format string - eg “lt``d``” it will try and find a suitable id. It scans list of devices to build up a free map, then chooses the first empty slot. The caller must hold the dev_base or rtnl lock while allocating the name and adding the device in order to avoid duplicates. Limited to bits_per_byte * page size devices (ie 32K on most platforms). Returns the number of the unit assigned or a negative errno code.
-
int
dev_set_alias
(struct net_device *dev, const char *alias, size_t len)¶ change ifalias of a device
Parameters
struct net_device *dev
device
const char *alias
name up to IFALIASZ
size_t len
limit of bytes to copy from info
Set ifalias for a device,
-
void
netdev_features_change
(struct net_device *dev)¶ device changes features
Parameters
struct net_device *dev
device to cause notification
Called to indicate a device has changed features.
-
void
netdev_state_change
(struct net_device *dev)¶ device changes state
Parameters
struct net_device *dev
device to cause notification
Called to indicate a device has changed state. This function calls the notifier chains for netdev_chain and sends a NEWLINK message to the routing socket.
-
void
__netdev_notify_peers
(struct net_device *dev)¶ notify network peers about existence of dev, to be called when rtnl lock is already held.
Parameters
struct net_device *dev
network device
Description
Generate traffic such that interested network peers are aware of dev, such as by generating a gratuitous ARP. This may be used when a device wants to inform the rest of the network about some sort of reconfiguration such as a failover event or virtual machine migration.
-
void
netdev_notify_peers
(struct net_device *dev)¶ notify network peers about existence of dev
Parameters
struct net_device *dev
network device
Description
Generate traffic such that interested network peers are aware of dev, such as by generating a gratuitous ARP. This may be used when a device wants to inform the rest of the network about some sort of reconfiguration such as a failover event or virtual machine migration.
-
int
dev_open
(struct net_device *dev, struct netlink_ext_ack *extack)¶ prepare an interface for use.
Parameters
struct net_device *dev
device to open
struct netlink_ext_ack *extack
netlink extended ack
Takes a device from down to up state. The device’s private open function is invoked and then the multicast lists are loaded. Finally the device is moved into the up state and a
NETDEV_UP
message is sent to the netdev notifier chain.Calling this function on an active interface is a nop. On a failure a negative errno code is returned.
-
void
dev_close
(struct net_device *dev)¶ shutdown an interface.
Parameters
struct net_device *dev
device to shutdown
This function moves an active device into down state. A
NETDEV_GOING_DOWN
is sent to the netdev notifier chain. The device is then deactivated and finally aNETDEV_DOWN
is sent to the notifier chain.
-
void
dev_disable_lro
(struct net_device *dev)¶ disable Large Receive Offload on a device
Parameters
struct net_device *dev
device
Disable Large Receive Offload (LRO) on a net device. Must be called under RTNL. This is needed if received packets may be forwarded to another interface.
-
int
register_netdevice_notifier
(struct notifier_block *nb)¶ register a network notifier block
Parameters
struct notifier_block *nb
notifier
Description
Register a notifier to be called when network device events occur. The notifier passed is linked into the kernel structures and must not be reused until it has been unregistered. A negative errno code is returned on a failure.
When registered all registration and up events are replayed to the new notifier to allow device to have a race free view of the network device list.
-
int
unregister_netdevice_notifier
(struct notifier_block *nb)¶ unregister a network notifier block
Parameters
struct notifier_block *nb
notifier
Description
Unregister a notifier previously registered by
register_netdevice_notifier()
. The notifier is unlinked into the
kernel structures and may then be reused. A negative errno code
is returned on a failure.
After unregistering unregister and down device events are synthesized for all devices on the device list to the removed notifier to remove the need for special case cleanup code.
-
int
register_netdevice_notifier_net
(struct net *net, struct notifier_block *nb)¶ register a per-netns network notifier block
Parameters
struct net *net
network namespace
struct notifier_block *nb
notifier
Description
Register a notifier to be called when network device events occur. The notifier passed is linked into the kernel structures and must not be reused until it has been unregistered. A negative errno code is returned on a failure.
When registered all registration and up events are replayed to the new notifier to allow device to have a race free view of the network device list.
-
int
unregister_netdevice_notifier_net
(struct net *net, struct notifier_block *nb)¶ unregister a per-netns network notifier block
Parameters
struct net *net
network namespace
struct notifier_block *nb
notifier
Description
Unregister a notifier previously registered by
register_netdevice_notifier()
. The notifier is unlinked into the
kernel structures and may then be reused. A negative errno code
is returned on a failure.
After unregistering unregister and down device events are synthesized for all devices on the device list to the removed notifier to remove the need for special case cleanup code.
-
int
call_netdevice_notifiers
(unsigned long val, struct net_device *dev)¶ call all network notifier blocks
Parameters
unsigned long val
value passed unmodified to notifier function
struct net_device *dev
net_device pointer passed unmodified to notifier function
Call all network notifier blocks. Parameters and return value are as for raw_notifier_call_chain().
-
int
dev_forward_skb
(struct net_device *dev, struct sk_buff *skb)¶ loopback an skb to another netif
Parameters
struct net_device *dev
destination network device
struct sk_buff *skb
buffer to forward
Description
- return values:
NET_RX_SUCCESS (no congestion) NET_RX_DROP (packet was dropped, but freed)
dev_forward_skb can be used for injecting an skb from the start_xmit function of one device into the receive queue of another device.
The receiving device may be in another namespace, so we have to clear all information in the skb that could impact namespace isolation.
-
bool
dev_nit_active
(struct net_device *dev)¶ return true if any network interface taps are in use
Parameters
struct net_device *dev
network device to check for the presence of taps
-
int
netif_set_real_num_rx_queues
(struct net_device *dev, unsigned int rxq)¶ set actual number of RX queues used
Parameters
struct net_device *dev
Network device
unsigned int rxq
Actual number of RX queues
This must be called either with the rtnl_lock held or before registration of the net device. Returns 0 on success, or a negative error code. If called before registration, it always succeeds.
-
int
netif_set_real_num_queues
(struct net_device *dev, unsigned int txq, unsigned int rxq)¶ set actual number of RX and TX queues used
Parameters
struct net_device *dev
Network device
unsigned int txq
Actual number of TX queues
unsigned int rxq
Actual number of RX queues
Set the real number of both TX and RX queues. Does nothing if the number of queues is already correct.
-
void
netif_set_tso_max_size
(struct net_device *dev, unsigned int size)¶ set the max size of TSO frames supported
Parameters
struct net_device *dev
netdev to update
unsigned int size
max skb->len of a TSO frame
Description
Set the limit on the size of TSO super-frames the device can handle.
Unless explicitly set the stack will assume the value of GSO_MAX_SIZE
.
-
void
netif_set_tso_max_segs
(struct net_device *dev, unsigned int segs)¶ set the max number of segs supported for TSO
Parameters
struct net_device *dev
netdev to update
unsigned int segs
max number of TCP segments
Description
Set the limit on the number of TCP segments the device can generate from
a single TSO super-frame.
Unless explicitly set the stack will assume the value of GSO_MAX_SEGS
.
-
void
netif_inherit_tso_max
(struct net_device *to, const struct net_device *from)¶ copy all TSO limits from a lower device to an upper
Parameters
struct net_device *to
netdev to update
const struct net_device *from
netdev from which to copy the limits
-
int
netif_get_num_default_rss_queues
(void)¶ default number of RSS queues
Parameters
void
no arguments
Description
This routine should set an upper limit on the number of RSS queues used by default by multiqueue devices.
-
void
netif_device_detach
(struct net_device *dev)¶ mark device as removed
Parameters
struct net_device *dev
network device
Description
Mark device as removed from system and therefore no longer available.
-
void
netif_device_attach
(struct net_device *dev)¶ mark device as attached
Parameters
struct net_device *dev
network device
Description
Mark device as attached from system and restart if needed.
-
struct sk_buff *
__skb_gso_segment
(struct sk_buff *skb, netdev_features_t features, bool tx_path)¶ Perform segmentation on skb.
Parameters
struct sk_buff *skb
buffer to segment
netdev_features_t features
features for the output path (see dev->features)
bool tx_path
whether it is called in TX path
This function segments the given skb and returns a list of segments.
It may return NULL if the skb requires no segmentation. This is only possible when GSO is used for verifying header integrity.
Segmentation preserves SKB_GSO_CB_OFFSET bytes of previous skb cb.
-
int
dev_loopback_xmit
(struct net *net, struct sock *sk, struct sk_buff *skb)¶ loop back skb
Parameters
struct net *net
network namespace this loopback is happening in
struct sock *sk
sk needed to be a netfilter okfn
struct sk_buff *skb
buffer to transmit
-
bool
rps_may_expire_flow
(struct net_device *dev, u16 rxq_index, u32 flow_id, u16 filter_id)¶ check whether an RFS hardware filter may be removed
Parameters
struct net_device *dev
Device on which the filter was set
u16 rxq_index
RX queue index
u32 flow_id
Flow ID passed to ndo_rx_flow_steer()
u16 filter_id
Filter ID returned by ndo_rx_flow_steer()
Description
Drivers that implement ndo_rx_flow_steer() should periodically call
this function for each installed filter and remove the filters for
which it returns true
.
-
int
netif_rx
(struct sk_buff *skb)¶ post buffer to the network code
Parameters
struct sk_buff *skb
buffer to post
This function receives a packet from a device driver and queues it for the upper (protocol) levels to process. It always succeeds. The buffer may be dropped during processing for congestion control or by the protocol layers.
return values: NET_RX_SUCCESS (no congestion) NET_RX_DROP (packet was dropped)
-
bool
netdev_is_rx_handler_busy
(struct net_device *dev)¶ check if receive handler is registered
Parameters
struct net_device *dev
device to check
Check if a receive handler is already registered for a given device. Return true if there one.
The caller must hold the rtnl_mutex.
-
int
netdev_rx_handler_register
(struct net_device *dev, rx_handler_func_t *rx_handler, void *rx_handler_data)¶ register receive handler
Parameters
struct net_device *dev
device to register a handler for
rx_handler_func_t *rx_handler
receive handler to register
void *rx_handler_data
data pointer that is used by rx handler
Register a receive handler for a device. This handler will then be called from __netif_receive_skb. A negative errno code is returned on a failure.
The caller must hold the rtnl_mutex.
For a general description of rx_handler, see enum rx_handler_result.
-
void
netdev_rx_handler_unregister
(struct net_device *dev)¶ unregister receive handler
Parameters
struct net_device *dev
device to unregister a handler from
Unregister a receive handler from a device.
The caller must hold the rtnl_mutex.
-
int
netif_receive_skb_core
(struct sk_buff *skb)¶ special purpose version of netif_receive_skb
Parameters
struct sk_buff *skb
buffer to process
More direct receive version of
netif_receive_skb()
. It should only be used by callers that have a need to skip RPS and Generic XDP. Caller must also take care of handling if(page_is_)pfmemalloc
.This function may only be called from softirq context and interrupts should be enabled.
Return values (usually ignored): NET_RX_SUCCESS: no congestion NET_RX_DROP: packet was dropped
-
int
netif_receive_skb
(struct sk_buff *skb)¶ process receive buffer from network
Parameters
struct sk_buff *skb
buffer to process
netif_receive_skb()
is the main receive data processing function. It always succeeds. The buffer may be dropped during processing for congestion control or by the protocol layers.This function may only be called from softirq context and interrupts should be enabled.
Return values (usually ignored): NET_RX_SUCCESS: no congestion NET_RX_DROP: packet was dropped
-
void
netif_receive_skb_list
(struct list_head *head)¶ process many receive buffers from network
Parameters
struct list_head *head
list of skbs to process.
Since return value of
netif_receive_skb()
is normally ignored, and wouldn’t be meaningful for a list, this function returns void.This function may only be called from softirq context and interrupts should be enabled.
-
void
__napi_schedule
(struct napi_struct *n)¶ schedule for receive
Parameters
struct napi_struct *n
entry to schedule
Description
The entry’s receive function will be scheduled to run.
Consider using __napi_schedule_irqoff()
if hard irqs are masked.
-
bool
napi_schedule_prep
(struct napi_struct *n)¶ check if napi can be scheduled
Parameters
struct napi_struct *n
napi context
Description
Test if NAPI routine is already running, and if not mark it as running. This is used as a condition variable to insure only one NAPI poll instance runs. We also make sure there is no pending NAPI disable.
-
void
__napi_schedule_irqoff
(struct napi_struct *n)¶ schedule for receive
Parameters
struct napi_struct *n
entry to schedule
Description
Variant of __napi_schedule()
assuming hard irqs are masked.
On PREEMPT_RT enabled kernels this maps to __napi_schedule()
because the interrupt disabled assumption might not be true
due to force-threaded interrupts and spinlock substitution.
-
void
napi_enable
(struct napi_struct *n)¶ enable NAPI scheduling
Parameters
struct napi_struct *n
NAPI context
Description
Resume NAPI from being scheduled on this context. Must be paired with napi_disable.
-
bool
netdev_has_upper_dev
(struct net_device *dev, struct net_device *upper_dev)¶ Check if device is linked to an upper device
Parameters
struct net_device *dev
device
struct net_device *upper_dev
upper device to check
Description
Find out if a device is linked to specified upper device and return true in case it is. Note that this checks only immediate upper device, not through a complete stack of devices. The caller must hold the RTNL lock.
-
bool
netdev_has_upper_dev_all_rcu
(struct net_device *dev, struct net_device *upper_dev)¶ Check if device is linked to an upper device
Parameters
struct net_device *dev
device
struct net_device *upper_dev
upper device to check
Description
Find out if a device is linked to specified upper device and return true in case it is. Note that this checks the entire upper device chain. The caller must hold rcu lock.
-
bool
netdev_has_any_upper_dev
(struct net_device *dev)¶ Check if device is linked to some device
Parameters
struct net_device *dev
device
Description
Find out if a device is linked to an upper device and return true in case it is. The caller must hold the RTNL lock.
-
struct net_device *
netdev_master_upper_dev_get
(struct net_device *dev)¶ Get master upper device
Parameters
struct net_device *dev
device
Description
Find a master upper device and return pointer to it or NULL in case it’s not there. The caller must hold the RTNL lock.
-
struct net_device *
netdev_upper_get_next_dev_rcu
(struct net_device *dev, struct list_head **iter)¶ Get the next dev from upper list
Parameters
struct net_device *dev
device
struct list_head **iter
list_head ** of the current position
Description
Gets the next device from the dev’s upper list, starting from iter position. The caller must hold RCU read lock.
-
void *
netdev_lower_get_next_private
(struct net_device *dev, struct list_head **iter)¶ Get the next ->private from the lower neighbour list
Parameters
struct net_device *dev
device
struct list_head **iter
list_head ** of the current position
Description
Gets the next netdev_adjacent->private from the dev’s lower neighbour list, starting from iter position. The caller must hold either hold the RTNL lock or its own locking that guarantees that the neighbour lower list will remain unchanged.
-
void *
netdev_lower_get_next_private_rcu
(struct net_device *dev, struct list_head **iter)¶ Get the next ->private from the lower neighbour list, RCU variant
Parameters
struct net_device *dev
device
struct list_head **iter
list_head ** of the current position
Description
Gets the next netdev_adjacent->private from the dev’s lower neighbour list, starting from iter position. The caller must hold RCU read lock.
-
void *
netdev_lower_get_next
(struct net_device *dev, struct list_head **iter)¶ Get the next device from the lower neighbour list
Parameters
struct net_device *dev
device
struct list_head **iter
list_head ** of the current position
Description
Gets the next netdev_adjacent from the dev’s lower neighbour list, starting from iter position. The caller must hold RTNL lock or its own locking that guarantees that the neighbour lower list will remain unchanged.
-
void *
netdev_lower_get_first_private_rcu
(struct net_device *dev)¶ Get the first ->private from the lower neighbour list, RCU variant
Parameters
struct net_device *dev
device
Description
Gets the first netdev_adjacent->private from the dev’s lower neighbour list. The caller must hold RCU read lock.
-
struct net_device *
netdev_master_upper_dev_get_rcu
(struct net_device *dev)¶ Get master upper device
Parameters
struct net_device *dev
device
Description
Find a master upper device and return pointer to it or NULL in case it’s not there. The caller must hold the RCU read lock.
-
int
netdev_upper_dev_link
(struct net_device *dev, struct net_device *upper_dev, struct netlink_ext_ack *extack)¶ Add a link to the upper device
Parameters
struct net_device *dev
device
struct net_device *upper_dev
new upper device
struct netlink_ext_ack *extack
netlink extended ack
Description
Adds a link to device which is upper to this one. The caller must hold the RTNL lock. On a failure a negative errno code is returned. On success the reference counts are adjusted and the function returns zero.
-
int
netdev_master_upper_dev_link
(struct net_device *dev, struct net_device *upper_dev, void *upper_priv, void *upper_info, struct netlink_ext_ack *extack)¶ Add a master link to the upper device
Parameters
struct net_device *dev
device
struct net_device *upper_dev
new upper device
void *upper_priv
upper device private
void *upper_info
upper info to be passed down via notifier
struct netlink_ext_ack *extack
netlink extended ack
Description
Adds a link to device which is upper to this one. In this case, only one master upper device can be linked, although other non-master devices might be linked as well. The caller must hold the RTNL lock. On a failure a negative errno code is returned. On success the reference counts are adjusted and the function returns zero.
-
void
netdev_upper_dev_unlink
(struct net_device *dev, struct net_device *upper_dev)¶ Removes a link to upper device
Parameters
struct net_device *dev
device
struct net_device *upper_dev
new upper device
Description
Removes a link to device which is upper to this one. The caller must hold the RTNL lock.
-
void
netdev_bonding_info_change
(struct net_device *dev, struct netdev_bonding_info *bonding_info)¶ Dispatch event about slave change
Parameters
struct net_device *dev
device
struct netdev_bonding_info *bonding_info
info to dispatch
Description
Send NETDEV_BONDING_INFO to netdev notifiers with info. The caller must hold the RTNL lock.
-
struct net_device *
netdev_get_xmit_slave
(struct net_device *dev, struct sk_buff *skb, bool all_slaves)¶ Get the xmit slave of master device
Parameters
struct net_device *dev
device
struct sk_buff *skb
The packet
bool all_slaves
assume all the slaves are active
Description
The reference counters are not incremented so the caller must be
careful with locks. The caller must hold RCU lock.
NULL
is returned if no slave is found.
-
struct net_device *
netdev_sk_get_lowest_dev
(struct net_device *dev, struct sock *sk)¶ Get the lowest device in chain given device and socket
Parameters
struct net_device *dev
device
struct sock *sk
the socket
Description
NULL
is returned if no lower device is found.
-
void
netdev_lower_state_changed
(struct net_device *lower_dev, void *lower_state_info)¶ Dispatch event about lower device state change
Parameters
struct net_device *lower_dev
device
void *lower_state_info
state to dispatch
Description
Send NETDEV_CHANGELOWERSTATE to netdev notifiers with info. The caller must hold the RTNL lock.
-
int
dev_set_promiscuity
(struct net_device *dev, int inc)¶ update promiscuity count on a device
Parameters
struct net_device *dev
device
int inc
modifier
Add or remove promiscuity from a device. While the count in the device remains above zero the interface remains promiscuous. Once it hits zero the device reverts back to normal filtering operation. A negative inc value is used to drop promiscuity on the device. Return 0 if successful or a negative errno code on error.
-
int
dev_set_allmulti
(struct net_device *dev, int inc)¶ update allmulti count on a device
Parameters
struct net_device *dev
device
int inc
modifier
Add or remove reception of all multicast frames to a device. While the count in the device remains above zero the interface remains listening to all interfaces. Once it hits zero the device reverts back to normal filtering operation. A negative inc value is used to drop the counter when releasing a resource needing all multicasts. Return 0 if successful or a negative errno code on error.
-
unsigned int
dev_get_flags
(const struct net_device *dev)¶ get flags reported to userspace
Parameters
const struct net_device *dev
device
Get the combination of flag bits exported through APIs to userspace.
-
int
dev_change_flags
(struct net_device *dev, unsigned int flags, struct netlink_ext_ack *extack)¶ change device settings
Parameters
struct net_device *dev
device
unsigned int flags
device state flags
struct netlink_ext_ack *extack
netlink extended ack
Change settings on device based state flags. The flags are in the userspace exported format.
-
void
dev_set_group
(struct net_device *dev, int new_group)¶ Change group this device belongs to
Parameters
struct net_device *dev
device
int new_group
group this device should belong to
-
int
dev_pre_changeaddr_notify
(struct net_device *dev, const char *addr, struct netlink_ext_ack *extack)¶ Call NETDEV_PRE_CHANGEADDR.
Parameters
struct net_device *dev
device
const char *addr
new address
struct netlink_ext_ack *extack
netlink extended ack
-
int
dev_set_mac_address
(struct net_device *dev, struct sockaddr *sa, struct netlink_ext_ack *extack)¶ Change Media Access Control Address
Parameters
struct net_device *dev
device
struct sockaddr *sa
new address
struct netlink_ext_ack *extack
netlink extended ack
Change the hardware (MAC) address of the device
-
int
dev_change_carrier
(struct net_device *dev, bool new_carrier)¶ Change device carrier
Parameters
struct net_device *dev
device
bool new_carrier
new value
Change device carrier
-
int
dev_get_phys_port_id
(struct net_device *dev, struct netdev_phys_item_id *ppid)¶ Get device physical port ID
Parameters
struct net_device *dev
device
struct netdev_phys_item_id *ppid
port ID
Get device physical port ID
-
int
dev_get_phys_port_name
(struct net_device *dev, char *name, size_t len)¶ Get device physical port name
Parameters
struct net_device *dev
device
char *name
port name
size_t len
limit of bytes to copy to name
Get device physical port name
-
int
dev_get_port_parent_id
(struct net_device *dev, struct netdev_phys_item_id *ppid, bool recurse)¶ Get the device’s port parent identifier
Parameters
struct net_device *dev
network device
struct netdev_phys_item_id *ppid
pointer to a storage for the port’s parent identifier
bool recurse
allow/disallow recursion to lower devices
Get the devices’s port parent identifier
-
bool
netdev_port_same_parent_id
(struct net_device *a, struct net_device *b)¶ Indicate if two network devices have the same port parent identifier
Parameters
struct net_device *a
first network device
struct net_device *b
second network device
-
int
dev_change_proto_down
(struct net_device *dev, bool proto_down)¶ update protocol port state information
Parameters
struct net_device *dev
device
bool proto_down
new value
This info can be used by switch drivers to set the phys state of the port.
-
int
dev_change_proto_down_generic
(struct net_device *dev, bool proto_down)¶ generic implementation for ndo_change_proto_down that sets carrier according to proto_down.
Parameters
struct net_device *dev
device
bool proto_down
new value
-
void
dev_change_proto_down_reason
(struct net_device *dev, unsigned long mask, u32 value)¶ proto down reason
Parameters
struct net_device *dev
device
unsigned long mask
proto down mask
u32 value
proto down value
-
void
netdev_update_features
(struct net_device *dev)¶ recalculate device features
Parameters
struct net_device *dev
the device to check
Recalculate dev->features set and send notifications if it has changed. Should be called after driver or hardware dependent conditions might have changed that influence the features.
-
void
netdev_change_features
(struct net_device *dev)¶ recalculate device features
Parameters
struct net_device *dev
the device to check
Recalculate dev->features set and send notifications even if they have not changed. Should be called instead of
netdev_update_features()
if also dev->vlan_features might have changed to allow the changes to be propagated to stacked VLAN devices.
-
void
netif_stacked_transfer_operstate
(const struct net_device *rootdev, struct net_device *dev)¶ transfer operstate
Parameters
const struct net_device *rootdev
the root or lower level device to transfer state from
struct net_device *dev
the device to transfer operstate to
Transfer operational state from root to device. This is normally called when a stacking relationship exists between the root device and the device(a leaf device).
-
int
register_netdevice
(struct net_device *dev)¶ register a network device
Parameters
struct net_device *dev
device to register
Take a completed network device structure and add it to the kernel interfaces. A
NETDEV_REGISTER
message is sent to the netdev notifier chain. 0 is returned on success. A negative errno code is returned on a failure to set up the device, or if the name is a duplicate.Callers must hold the rtnl semaphore. You may want
register_netdev()
instead of this.BUGS: The locking appears insufficient to guarantee two parallel registers will not get the same name.
-
int
init_dummy_netdev
(struct net_device *dev)¶ init a dummy network device for NAPI
Parameters
struct net_device *dev
device to init
This takes a network device structure and initialize the minimum amount of fields so it can be used to schedule NAPI polls without registering a full blown interface. This is to be used by drivers that need to tie several hardware interfaces to a single NAPI poll scheduler due to HW limitations.
-
int
register_netdev
(struct net_device *dev)¶ register a network device
Parameters
struct net_device *dev
device to register
Take a completed network device structure and add it to the kernel interfaces. A
NETDEV_REGISTER
message is sent to the netdev notifier chain. 0 is returned on success. A negative errno code is returned on a failure to set up the device, or if the name is a duplicate.This is a wrapper around register_netdevice that takes the rtnl semaphore and expands the device name if you passed a format string to alloc_netdev.
-
struct rtnl_link_stats64 *
dev_get_stats
(struct net_device *dev, struct rtnl_link_stats64 *storage)¶ get network device statistics
Parameters
struct net_device *dev
device to get statistics from
struct rtnl_link_stats64 *storage
place to store stats
Get network statistics from device. Return storage. The device driver may provide its own method by setting dev->netdev_ops->get_stats64 or dev->netdev_ops->get_stats; otherwise the internal statistics structure is used.
-
void
dev_fetch_sw_netstats
(struct rtnl_link_stats64 *s, const struct pcpu_sw_netstats __percpu *netstats)¶ get per-cpu network device statistics
Parameters
struct rtnl_link_stats64 *s
place to store stats
const struct pcpu_sw_netstats __percpu *netstats
per-cpu network stats to read from
Read per-cpu network statistics and populate the related fields in s.
-
void
dev_get_tstats64
(struct net_device *dev, struct rtnl_link_stats64 *s)¶ ndo_get_stats64 implementation
Parameters
struct net_device *dev
device to get statistics from
struct rtnl_link_stats64 *s
place to store stats
Populate s from dev->stats and dev->tstats. Can be used as ndo_get_stats64() callback.
-
struct net_device *
alloc_netdev_mqs
(int sizeof_priv, const char *name, unsigned char name_assign_type, void (*setup)(struct net_device *), unsigned int txqs, unsigned int rxqs)¶ allocate network device
Parameters
int sizeof_priv
size of private data to allocate space for
const char *name
device name format string
unsigned char name_assign_type
origin of device name
void (*setup)(struct net_device *)
callback to initialize device
unsigned int txqs
the number of TX subqueues to allocate
unsigned int rxqs
the number of RX subqueues to allocate
Description
Allocates a struct net_device with private data area for driver use and performs basic initialization. Also allocates subqueue structs for each queue on the device.
-
void
free_netdev
(struct net_device *dev)¶ free network device
Parameters
struct net_device *dev
device
Description
This function does the last stage of destroying an allocated device interface. The reference to the device object is released. If this is the last reference then it will be freed.Must be called in process context.
-
void
synchronize_net
(void)¶ Synchronize with packet receive processing
Parameters
void
no arguments
Description
Wait for packets currently being received to be done. Does not block later packets from starting.
-
void
unregister_netdevice_queue
(struct net_device *dev, struct list_head *head)¶ remove device from the kernel
Parameters
struct net_device *dev
device
struct list_head *head
list
This function shuts down a device interface and removes it from the kernel tables. If head not NULL, device is queued to be unregistered later.
Callers must hold the rtnl semaphore. You may want
unregister_netdev()
instead of this.
-
void
unregister_netdevice_many
(struct list_head *head)¶ unregister many devices
Parameters
struct list_head *head
list of devices
Note
- As most callers use a stack allocated list_head,
we force a
list_del()
to make sure stack wont be corrupted later.
-
void
unregister_netdev
(struct net_device *dev)¶ remove device from the kernel
Parameters
struct net_device *dev
device
This function shuts down a device interface and removes it from the kernel tables.
This is just a wrapper for unregister_netdevice that takes the rtnl semaphore. In general you want to use this and not unregister_netdevice.
-
int
__dev_change_net_namespace
(struct net_device *dev, struct net *net, const char *pat, int new_ifindex)¶ move device to different nethost namespace
Parameters
struct net_device *dev
device
struct net *net
network namespace
const char *pat
If not NULL name pattern to try if the current device name is already taken in the destination network namespace.
int new_ifindex
If not zero, specifies device index in the target namespace.
This function shuts down a device interface and moves it to a new network namespace. On success 0 is returned, on a failure a netagive errno code is returned.
Callers must hold the rtnl semaphore.
-
netdev_features_t
netdev_increment_features
(netdev_features_t all, netdev_features_t one, netdev_features_t mask)¶ increment feature set by one
Parameters
netdev_features_t all
current feature set
netdev_features_t one
new feature set
netdev_features_t mask
mask feature set
Computes a new feature set after adding a device with feature set one to the master device with current feature set all. Will not enable anything that is off in mask. Returns the new feature set.
-
int
eth_header
(struct sk_buff *skb, struct net_device *dev, unsigned short type, const void *daddr, const void *saddr, unsigned int len)¶ create the Ethernet header
Parameters
struct sk_buff *skb
buffer to alter
struct net_device *dev
source device
unsigned short type
Ethernet type field
const void *daddr
destination address (NULL leave destination address)
const void *saddr
source address (NULL use device source address)
unsigned int len
packet length (<= skb->len)
Description
Set the protocol type. For a packet of type ETH_P_802_3/2 we put the length in here instead.
-
u32
eth_get_headlen
(const struct net_device *dev, const void *data, u32 len)¶ determine the length of header for an ethernet frame
Parameters
const struct net_device *dev
pointer to network device
const void *data
pointer to start of frame
u32 len
total length of frame
Description
Make a best effort attempt to pull the length for all of the headers for a given frame in a linear buffer.
-
__be16
eth_type_trans
(struct sk_buff *skb, struct net_device *dev)¶ determine the packet’s protocol ID.
Parameters
struct sk_buff *skb
received socket data
struct net_device *dev
receiving network device
Description
The rule here is that we assume 802.3 if the type field is short enough to be a length. This is normal practice and works for any ‘now in use’ protocol.
-
int
eth_header_parse
(const struct sk_buff *skb, unsigned char *haddr)¶ extract hardware address from packet
Parameters
const struct sk_buff *skb
packet to extract header from
unsigned char *haddr
destination buffer
-
int
eth_header_cache
(const struct neighbour *neigh, struct hh_cache *hh, __be16 type)¶ fill cache entry from neighbour
Parameters
const struct neighbour *neigh
source neighbour
struct hh_cache *hh
destination cache entry
__be16 type
Ethernet type field
Description
Create an Ethernet header template from the neighbour.
-
void
eth_header_cache_update
(struct hh_cache *hh, const struct net_device *dev, const unsigned char *haddr)¶ update cache entry
Parameters
struct hh_cache *hh
destination cache entry
const struct net_device *dev
network device
const unsigned char *haddr
new hardware address
Description
Called by Address Resolution module to notify changes in address.
-
__be16
eth_header_parse_protocol
(const struct sk_buff *skb)¶ extract protocol from L2 header
Parameters
const struct sk_buff *skb
packet to extract protocol from
-
int
eth_prepare_mac_addr_change
(struct net_device *dev, void *p)¶ prepare for mac change
Parameters
struct net_device *dev
network device
void *p
socket address
-
void
eth_commit_mac_addr_change
(struct net_device *dev, void *p)¶ commit mac change
Parameters
struct net_device *dev
network device
void *p
socket address
-
int
eth_mac_addr
(struct net_device *dev, void *p)¶ set new Ethernet hardware address
Parameters
struct net_device *dev
network device
void *p
socket address
Description
Change hardware address of device.
This doesn’t change hardware matching, so needs to be overridden for most real devices.
-
void
ether_setup
(struct net_device *dev)¶ setup Ethernet network device
Parameters
struct net_device *dev
network device
Description
Fill in the fields of the device structure with Ethernet-generic values.
-
struct net_device *
alloc_etherdev_mqs
(int sizeof_priv, unsigned int txqs, unsigned int rxqs)¶ Allocates and sets up an Ethernet device
Parameters
int sizeof_priv
Size of additional driver-private structure to be allocated for this Ethernet device
unsigned int txqs
The number of TX queues this device has.
unsigned int rxqs
The number of RX queues this device has.
Description
Fill in the fields of the device structure with Ethernet-generic values. Basically does everything except registering the device.
Constructs a new net device, complete with a private data area of size (sizeof_priv). A 32-byte (not bit) alignment is enforced for this private data area.
-
int
platform_get_ethdev_address
(struct device *dev, struct net_device *netdev)¶ Set netdev’s MAC address from a given device
Parameters
struct device *dev
Pointer to the device
struct net_device *netdev
Pointer to netdev to write the address to
Description
Wrapper around eth_platform_get_mac_address() which writes the address directly to netdev->dev_addr.
-
int
nvmem_get_mac_address
(struct device *dev, void *addrbuf)¶ Obtain the MAC address from an nvmem cell named ‘mac-address’ associated with given device.
Parameters
struct device *dev
Device with which the mac-address cell is associated.
void *addrbuf
Buffer to which the MAC address will be copied on success.
Description
Returns 0 on success or a negative error number on failure.
-
int
fwnode_get_mac_address
(struct fwnode_handle *fwnode, char *addr)¶ Get the MAC from the firmware node
Parameters
struct fwnode_handle *fwnode
Pointer to the firmware node
char *addr
Address of buffer to store the MAC in
Description
Search the firmware node for the best MAC address to use. ‘mac-address’ is checked first, because that is supposed to contain to “most recent” MAC address. If that isn’t set, then ‘local-mac-address’ is checked next, because that is the default address. If that isn’t set, then the obsolete ‘address’ is checked, just in case we’re using an old device tree.
Note that the ‘address’ property is supposed to contain a virtual address of the register set, but some DTS files have redefined that property to be the MAC address.
All-zero MAC addresses are rejected, because those could be properties that exist in the firmware tables, but were not updated by the firmware. For example, the DTS could define ‘mac-address’ and ‘local-mac-address’, with zero MAC addresses. Some older U-Boots only initialized ‘local-mac-address’. In this case, the real MAC is in ‘local-mac-address’, and ‘mac-address’ exists but is all zeros.
-
int
device_get_mac_address
(struct device *dev, char *addr)¶ Get the MAC for a given device
Parameters
struct device *dev
Pointer to the device
char *addr
Address of buffer to store the MAC in
-
int
device_get_ethdev_address
(struct device *dev, struct net_device *netdev)¶ Set netdev’s MAC address from a given device
Parameters
struct device *dev
Pointer to the device
struct net_device *netdev
Pointer to netdev to write the address to
Description
Wrapper around device_get_mac_address()
which writes the address
directly to netdev->dev_addr.
-
void
netif_carrier_on
(struct net_device *dev)¶ set carrier
Parameters
struct net_device *dev
network device
Description
Device has detected acquisition of carrier.
-
void
netif_carrier_off
(struct net_device *dev)¶ clear carrier
Parameters
struct net_device *dev
network device
Description
Device has detected loss of carrier.
-
void
netif_carrier_event
(struct net_device *dev)¶ report carrier state event
Parameters
struct net_device *dev
network device
Description
Device has detected a carrier event but the carrier state wasn’t changed. Use in drivers when querying carrier state asynchronously, to avoid missing events (link flaps) if link recovers before it’s queried.
-
bool
is_link_local_ether_addr
(const u8 *addr)¶ Determine if given Ethernet address is link-local
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if address is link local reserved addr (01:80:c2:00:00:0X) per IEEE 802.1Q 8.6.3 Frame filtering.
Please note: addr must be aligned to u16.
-
bool
is_zero_ether_addr
(const u8 *addr)¶ Determine if give Ethernet address is all zeros.
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if the address is all zeroes.
Please note: addr must be aligned to u16.
-
bool
is_multicast_ether_addr
(const u8 *addr)¶ Determine if the Ethernet address is a multicast.
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if the address is a multicast address. By definition the broadcast address is also a multicast address.
-
bool
is_local_ether_addr
(const u8 *addr)¶ Determine if the Ethernet address is locally-assigned one (IEEE 802).
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if the address is a local address.
-
bool
is_broadcast_ether_addr
(const u8 *addr)¶ Determine if the Ethernet address is broadcast
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if the address is the broadcast address.
Please note: addr must be aligned to u16.
-
bool
is_unicast_ether_addr
(const u8 *addr)¶ Determine if the Ethernet address is unicast
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return true if the address is a unicast address.
-
bool
is_valid_ether_addr
(const u8 *addr)¶ Determine if the given Ethernet address is valid
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Check that the Ethernet address (MAC) is not 00:00:00:00:00:00, is not a multicast address, and is not FF:FF:FF:FF:FF:FF.
Return true if the address is valid.
Please note: addr must be aligned to u16.
-
bool
eth_proto_is_802_3
(__be16 proto)¶ Determine if a given Ethertype/length is a protocol
Parameters
__be16 proto
Ethertype/length value to be tested
Description
Check that the value from the Ethertype/length field is a valid Ethertype.
Return true if the valid is an 802.3 supported Ethertype.
-
void
eth_random_addr
(u8 *addr)¶ Generate software assigned random Ethernet address
Parameters
u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Generate a random Ethernet address (MAC) that is not multicast and has the local assigned bit set.
-
void
eth_broadcast_addr
(u8 *addr)¶ Assign broadcast address
Parameters
u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Assign the broadcast address to the given address array.
-
void
eth_zero_addr
(u8 *addr)¶ Assign zero address
Parameters
u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Assign the zero address to the given address array.
-
void
eth_hw_addr_random
(struct net_device *dev)¶ Generate software assigned random Ethernet and set device flag
Parameters
struct net_device *dev
pointer to net_device structure
Description
Generate a random Ethernet address (MAC) to be used by a net device and set addr_assign_type so the state can be read by sysfs and be used by userspace.
-
u32
eth_hw_addr_crc
(struct netdev_hw_addr *ha)¶ Calculate CRC from netdev_hw_addr
Parameters
struct netdev_hw_addr *ha
pointer to hardware address
Description
Calculate CRC from a hardware address as basis for filter hashes.
-
void
ether_addr_copy
(u8 *dst, const u8 *src)¶ Copy an Ethernet address
Parameters
u8 *dst
Pointer to a six-byte array Ethernet address destination
const u8 *src
Pointer to a six-byte array Ethernet address source
Description
Please note: dst & src must both be aligned to u16.
-
void
eth_hw_addr_set
(struct net_device *dev, const u8 *addr)¶ Assign Ethernet address to a net_device
Parameters
struct net_device *dev
pointer to net_device structure
const u8 *addr
address to assign
Description
Assign given address to the net_device, addr_assign_type is not changed.
-
void
eth_hw_addr_inherit
(struct net_device *dst, struct net_device *src)¶ Copy dev_addr from another net_device
Parameters
struct net_device *dst
pointer to net_device to copy dev_addr to
struct net_device *src
pointer to net_device to copy dev_addr from
Description
Copy the Ethernet address from one net_device to another along with the address attributes (addr_assign_type).
-
bool
ether_addr_equal
(const u8 *addr1, const u8 *addr2)¶ Compare two Ethernet addresses
Parameters
const u8 *addr1
Pointer to a six-byte array containing the Ethernet address
const u8 *addr2
Pointer other six-byte array containing the Ethernet address
Description
Compare two Ethernet addresses, returns true if equal
Please note: addr1 & addr2 must both be aligned to u16.
-
bool
ether_addr_equal_64bits
(const u8 addr1[6+2], const u8 addr2[6+2])¶ Compare two Ethernet addresses
Parameters
const u8 addr1[6+2]
Pointer to an array of 8 bytes
const u8 addr2[6+2]
Pointer to an other array of 8 bytes
Description
Compare two Ethernet addresses, returns true if equal, false otherwise.
The function doesn’t need any conditional branches and possibly uses word memory accesses on CPU allowing cheap unaligned memory reads. arrays = { byte1, byte2, byte3, byte4, byte5, byte6, pad1, pad2 }
Please note that alignment of addr1 & addr2 are only guaranteed to be 16 bits.
-
bool
ether_addr_equal_unaligned
(const u8 *addr1, const u8 *addr2)¶ Compare two not u16 aligned Ethernet addresses
Parameters
const u8 *addr1
Pointer to a six-byte array containing the Ethernet address
const u8 *addr2
Pointer other six-byte array containing the Ethernet address
Description
Compare two Ethernet addresses, returns true if equal
Please note: Use only when any Ethernet address may not be u16 aligned.
-
bool
ether_addr_equal_masked
(const u8 *addr1, const u8 *addr2, const u8 *mask)¶ Compare two Ethernet addresses with a mask
Parameters
const u8 *addr1
Pointer to a six-byte array containing the 1st Ethernet address
const u8 *addr2
Pointer to a six-byte array containing the 2nd Ethernet address
const u8 *mask
Pointer to a six-byte array containing the Ethernet address bitmask
Description
Compare two Ethernet addresses with a mask, returns true if for every bit set in the bitmask the equivalent bits in the ethernet addresses are equal. Using a mask with all bits set is a slower ether_addr_equal.
-
u64
ether_addr_to_u64
(const u8 *addr)¶ Convert an Ethernet address into a u64 value.
Parameters
const u8 *addr
Pointer to a six-byte array containing the Ethernet address
Description
Return a u64 value of the address
-
void
u64_to_ether_addr
(u64 u, u8 *addr)¶ Convert a u64 to an Ethernet address.
Parameters
u64 u
u64 to convert to an Ethernet MAC address
u8 *addr
Pointer to a six-byte array to contain the Ethernet address
-
void
eth_addr_dec
(u8 *addr)¶ Decrement the given MAC address
Parameters
u8 *addr
Pointer to a six-byte array containing Ethernet address to decrement
-
void
eth_addr_inc
(u8 *addr)¶ Increment the given MAC address.
Parameters
u8 *addr
Pointer to a six-byte array containing Ethernet address to increment.
-
bool
is_etherdev_addr
(const struct net_device *dev, const u8 addr[6 + 2])¶ Tell if given Ethernet address belongs to the device.
Parameters
const struct net_device *dev
Pointer to a device structure
const u8 addr[6 + 2]
Pointer to a six-byte array containing the Ethernet address
Description
Compare passed address with all addresses of the device. Return true if the address if one of the device addresses.
Note that this function calls ether_addr_equal_64bits()
so take care of
the right padding.
-
unsigned long
compare_ether_header
(const void *a, const void *b)¶ Compare two Ethernet headers
Parameters
const void *a
Pointer to Ethernet header
const void *b
Pointer to Ethernet header
Description
Compare two Ethernet headers, returns 0 if equal. This assumes that the network header (i.e., IP header) is 4-byte aligned OR the platform can handle unaligned access. This is the case for all packets coming into netif_receive_skb or similar entry points.
-
void
eth_hw_addr_gen
(struct net_device *dev, const u8 *base_addr, unsigned int id)¶ Generate and assign Ethernet address to a port
Parameters
struct net_device *dev
pointer to port’s net_device structure
const u8 *base_addr
base Ethernet address
unsigned int id
offset to add to the base address
Description
Generate a MAC address using a base address and an offset and assign it to a net_device. Commonly used by switch drivers which need to compute addresses for all their ports. addr_assign_type is not changed.
-
int
eth_skb_pad
(struct sk_buff *skb)¶ Pad buffer to mininum number of octets for Ethernet frame
Parameters
struct sk_buff *skb
Buffer to pad
Description
An Ethernet frame should have a minimum size of 60 bytes. This function takes short frames and pads them with zeros up to the 60 byte limit.
Error
kernel-doc missing
PHY Support¶
-
void
phy_print_status
(struct phy_device *phydev)¶ Convenience function to print out the current phy status
Parameters
struct phy_device *phydev
the phy_device struct
-
int
phy_restart_aneg
(struct phy_device *phydev)¶ restart auto-negotiation
Parameters
struct phy_device *phydev
target phy_device struct
Description
Restart the autonegotiation on phydev. Returns >= 0 on success or negative errno on error.
-
int
phy_aneg_done
(struct phy_device *phydev)¶ return auto-negotiation status
Parameters
struct phy_device *phydev
target phy_device struct
Description
Return the auto-negotiation status from this phydev Returns > 0 on success or < 0 on error. 0 means that auto-negotiation is still pending.
-
int
phy_mii_ioctl
(struct phy_device *phydev, struct ifreq *ifr, int cmd)¶ generic PHY MII ioctl interface
Parameters
struct phy_device *phydev
the phy_device struct
struct ifreq *ifr
struct ifreq
for socket ioctl’sint cmd
ioctl cmd to execute
Description
Note that this function is currently incompatible with the PHYCONTROL layer. It changes registers without regard to current state. Use at own risk.
-
int
phy_do_ioctl
(struct net_device *dev, struct ifreq *ifr, int cmd)¶ generic ndo_eth_ioctl implementation
Parameters
struct net_device *dev
the net_device struct
struct ifreq *ifr
struct ifreq
for socket ioctl’sint cmd
ioctl cmd to execute
-
int
phy_do_ioctl_running
(struct net_device *dev, struct ifreq *ifr, int cmd)¶ generic ndo_eth_ioctl implementation but test first
Parameters
struct net_device *dev
the net_device struct
struct ifreq *ifr
struct ifreq
for socket ioctl’sint cmd
ioctl cmd to execute
Description
Same as phy_do_ioctl, but ensures that net_device is running before handling the ioctl.
-
void
phy_queue_state_machine
(struct phy_device *phydev, unsigned long jiffies)¶ Trigger the state machine to run soon
Parameters
struct phy_device *phydev
the phy_device struct
unsigned long jiffies
Run the state machine after these jiffies
-
void
phy_trigger_machine
(struct phy_device *phydev)¶ Trigger the state machine to run now
Parameters
struct phy_device *phydev
the phy_device struct
-
int
phy_ethtool_get_strings
(struct phy_device *phydev, u8 *data)¶ Get the statistic counter names
Parameters
struct phy_device *phydev
the phy_device struct
u8 *data
Where to put the strings
-
int
phy_ethtool_get_sset_count
(struct phy_device *phydev)¶ Get the number of statistic counters
Parameters
struct phy_device *phydev
the phy_device struct
-
int
phy_ethtool_get_stats
(struct phy_device *phydev, struct ethtool_stats *stats, u64 *data)¶ Get the statistic counters
Parameters
struct phy_device *phydev
the phy_device struct
struct ethtool_stats *stats
What counters to get
u64 *data
Where to store the counters
-
int
phy_start_cable_test
(struct phy_device *phydev, struct netlink_ext_ack *extack)¶ Start a cable test
Parameters
struct phy_device *phydev
the phy_device struct
struct netlink_ext_ack *extack
extack for reporting useful error messages
-
int
phy_start_cable_test_tdr
(struct phy_device *phydev, struct netlink_ext_ack *extack, const struct phy_tdr_config *config)¶ Start a raw TDR cable test
Parameters
struct phy_device *phydev
the phy_device struct
struct netlink_ext_ack *extack
extack for reporting useful error messages
const struct phy_tdr_config *config
Configuration of the test to run
-
int
phy_start_aneg
(struct phy_device *phydev)¶ start auto-negotiation for this PHY device
Parameters
struct phy_device *phydev
the phy_device struct
Description
- Sanitizes the settings (if we’re not autonegotiating
them), and then calls the driver’s config_aneg function. If the PHYCONTROL Layer is operating, we change the state to reflect the beginning of Auto-negotiation or forcing.
-
int
phy_speed_down
(struct phy_device *phydev, bool sync)¶ set speed to lowest speed supported by both link partners
Parameters
struct phy_device *phydev
the phy_device struct
bool sync
perform action synchronously
Description
Typically used to save energy when waiting for a WoL packet
WARNING: Setting sync to false may cause the system being unable to suspend in case the PHY generates an interrupt when finishing the autonegotiation. This interrupt may wake up the system immediately after suspend. Therefore use sync = false only if you’re sure it’s safe with the respective network chip.
-
int
phy_speed_up
(struct phy_device *phydev)¶ (re)set advertised speeds to all supported speeds
Parameters
struct phy_device *phydev
the phy_device struct
Description
Used to revert the effect of phy_speed_down
-
void
phy_start_machine
(struct phy_device *phydev)¶ start PHY state machine tracking
Parameters
struct phy_device *phydev
the phy_device struct
Description
- The PHY infrastructure can run a state machine
which tracks whether the PHY is starting up, negotiating, etc. This function starts the delayed workqueue which tracks the state of the PHY. If you want to maintain your own state machine, do not call this function.
-
void
phy_error
(struct phy_device *phydev)¶ enter HALTED state for this PHY device
Parameters
struct phy_device *phydev
target phy_device struct
Description
Moves the PHY to the HALTED state in response to a read or write error, and tells the controller the link is down. Must not be called from interrupt context, or while the phydev->lock is held.
-
void
phy_request_interrupt
(struct phy_device *phydev)¶ request and enable interrupt for a PHY device
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Request and enable the interrupt for the given PHY.
If this fails, then we set irq to PHY_POLL. This should only be called with a valid IRQ number.
-
void
phy_free_interrupt
(struct phy_device *phydev)¶ disable and free interrupt for a PHY device
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Disable and free the interrupt for the given PHY.
This should only be called with a valid IRQ number.
-
void
phy_stop
(struct phy_device *phydev)¶ Bring down the PHY link, and stop checking the status
Parameters
struct phy_device *phydev
target phy_device struct
-
void
phy_start
(struct phy_device *phydev)¶ start or restart a PHY device
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Indicates the attached device’s readiness to
handle PHY-related work. Used during startup to start the PHY, and after a call to
phy_stop()
to resume operation. Also used to indicate the MDIO bus has cleared an error condition.
-
void
phy_mac_interrupt
(struct phy_device *phydev)¶ MAC says the link has changed
Parameters
struct phy_device *phydev
phy_device struct with changed link
Description
The MAC layer is able to indicate there has been a change in the PHY link status. Trigger the state machine and work a work queue.
-
int
phy_init_eee
(struct phy_device *phydev, bool clk_stop_enable)¶ init and check the EEE feature
Parameters
struct phy_device *phydev
target phy_device struct
bool clk_stop_enable
PHY may stop the clock during LPI
Description
it checks if the Energy-Efficient Ethernet (EEE) is supported by looking at the MMD registers 3.20 and 7.60/61 and it programs the MMD register 3.0 setting the “Clock stop enable” bit if required.
-
int
phy_get_eee_err
(struct phy_device *phydev)¶ report the EEE wake error count
Parameters
struct phy_device *phydev
target phy_device struct
Description
it is to report the number of time where the PHY failed to complete its normal wake sequence.
-
int
phy_ethtool_get_eee
(struct phy_device *phydev, struct ethtool_eee *data)¶ get EEE supported and status
Parameters
struct phy_device *phydev
target phy_device struct
struct ethtool_eee *data
ethtool_eee data
Description
it reportes the Supported/Advertisement/LP Advertisement capabilities.
-
int
phy_ethtool_set_eee
(struct phy_device *phydev, struct ethtool_eee *data)¶ set EEE supported and status
Parameters
struct phy_device *phydev
target phy_device struct
struct ethtool_eee *data
ethtool_eee data
Description
it is to program the Advertisement EEE register.
-
int
phy_ethtool_set_wol
(struct phy_device *phydev, struct ethtool_wolinfo *wol)¶ Configure Wake On LAN
Parameters
struct phy_device *phydev
target phy_device struct
struct ethtool_wolinfo *wol
Configuration requested
-
void
phy_ethtool_get_wol
(struct phy_device *phydev, struct ethtool_wolinfo *wol)¶ Get the current Wake On LAN configuration
Parameters
struct phy_device *phydev
target phy_device struct
struct ethtool_wolinfo *wol
Store the current configuration here
-
int
phy_ethtool_nway_reset
(struct net_device *ndev)¶ Restart auto negotiation
Parameters
struct net_device *ndev
Network device to restart autoneg for
-
int
phy_config_interrupt
(struct phy_device *phydev, bool interrupts)¶ configure the PHY device for the requested interrupts
Parameters
struct phy_device *phydev
the phy_device struct
bool interrupts
interrupt flags to configure for this phydev
Description
Returns 0 on success or < 0 on error.
-
const struct phy_setting *
phy_find_valid
(int speed, int duplex, unsigned long *supported)¶ find a PHY setting that matches the requested parameters
Parameters
int speed
desired speed
int duplex
desired duplex
unsigned long *supported
mask of supported link modes
Description
Locate a supported phy setting that is, in priority order:
- an exact match for the specified speed and duplex mode
- a match for the specified speed, or slower speed
- the slowest supported speed
Returns the matched phy_setting entry, or NULL
if no supported phy
settings were found.
-
unsigned int
phy_supported_speeds
(struct phy_device *phy, unsigned int *speeds, unsigned int size)¶ return all speeds currently supported by a phy device
Parameters
struct phy_device *phy
The phy device to return supported speeds of.
unsigned int *speeds
buffer to store supported speeds in.
unsigned int size
size of speeds buffer.
Description
Returns the number of supported speeds, and fills the speeds buffer with the supported speeds. If speeds buffer is too small to contain all currently supported speeds, will return as many speeds as can fit.
-
bool
phy_check_valid
(int speed, int duplex, unsigned long *features)¶ check if there is a valid PHY setting which matches speed, duplex, and feature mask
Parameters
int speed
speed to match
int duplex
duplex to match
unsigned long *features
A mask of the valid settings
Description
Returns true if there is a valid setting, false otherwise.
-
void
phy_sanitize_settings
(struct phy_device *phydev)¶ make sure the PHY is set to supported speed and duplex
Parameters
struct phy_device *phydev
the target phy_device struct
Description
- Make sure the PHY is set to supported speeds and
duplexes. Drop down by one in this order: 1000/FULL, 1000/HALF, 100/FULL, 100/HALF, 10/FULL, 10/HALF.
-
int
phy_check_link_status
(struct phy_device *phydev)¶ check link status and set state accordingly
Parameters
struct phy_device *phydev
the phy_device struct
Description
Check for link and whether autoneg was triggered / is running and set state accordingly
-
int
_phy_start_aneg
(struct phy_device *phydev)¶ start auto-negotiation for this PHY device
Parameters
struct phy_device *phydev
the phy_device struct
Description
- Sanitizes the settings (if we’re not autonegotiating
them), and then calls the driver’s config_aneg function. If the PHYCONTROL Layer is operating, we change the state to reflect the beginning of Auto-negotiation or forcing.
-
void
phy_stop_machine
(struct phy_device *phydev)¶ stop the PHY state machine tracking
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Stops the state machine delayed workqueue, sets the
state to UP (unless it wasn’t up yet). This function must be called BEFORE phy_detach.
-
int
phy_disable_interrupts
(struct phy_device *phydev)¶ Disable the PHY interrupts from the PHY side
Parameters
struct phy_device *phydev
target phy_device struct
-
irqreturn_t
phy_interrupt
(int irq, void *phy_dat)¶ PHY interrupt handler
Parameters
int irq
interrupt line
void *phy_dat
phy_device pointer
Description
Handle PHY interrupt
-
int
phy_enable_interrupts
(struct phy_device *phydev)¶ Enable the interrupts from the PHY side
Parameters
struct phy_device *phydev
target phy_device struct
-
void
phy_state_machine
(struct work_struct *work)¶ Handle the state machine
Parameters
struct work_struct *work
work_struct that describes the work to be done
-
const char *
phy_speed_to_str
(int speed)¶ Return a string representing the PHY link speed
Parameters
int speed
Speed of the link
-
const char *
phy_duplex_to_str
(unsigned int duplex)¶ Return string describing the duplex
Parameters
unsigned int duplex
Duplex setting to describe
-
const struct phy_setting *
phy_lookup_setting
(int speed, int duplex, const unsigned long *mask, bool exact)¶ lookup a PHY setting
Parameters
int speed
speed to match
int duplex
duplex to match
const unsigned long *mask
allowed link modes
bool exact
an exact match is required
Description
Search the settings array for a setting that matches the speed and duplex, and which is supported.
If exact is unset, either an exact match or NULL
for no match will
be returned.
If exact is set, an exact match, the fastest supported setting at
or below the specified speed, the slowest supported setting, or if
they all fail, NULL
will be returned.
-
int
phy_set_max_speed
(struct phy_device *phydev, u32 max_speed)¶ Set the maximum speed the PHY should support
Parameters
struct phy_device *phydev
The phy_device struct
u32 max_speed
Maximum speed
Description
The PHY might be more capable than the MAC. For example a Fast Ethernet is connected to a 1G PHY. This function allows the MAC to indicate its maximum speed, and so limit what the PHY will advertise.
-
void
phy_resolve_aneg_pause
(struct phy_device *phydev)¶ Determine pause autoneg results
Parameters
struct phy_device *phydev
The phy_device struct
Description
Once autoneg has completed the local pause settings can be resolved. Determine if pause and asymmetric pause should be used by the MAC.
-
void
phy_resolve_aneg_linkmode
(struct phy_device *phydev)¶ resolve the advertisements into PHY settings
Parameters
struct phy_device *phydev
The phy_device struct
Description
Resolve our and the link partner advertisements into their corresponding speed and duplex. If full duplex was negotiated, extract the pause mode from the link partner mask.
-
void
phy_check_downshift
(struct phy_device *phydev)¶ check whether downshift occurred
Parameters
struct phy_device *phydev
The phy_device struct
Description
Check whether a downshift to a lower speed occurred. If this should be the case warn the user. Prerequisite for detecting downshift is that PHY driver implements the read_status callback and sets phydev->speed to the actual link speed.
-
int
__phy_read_mmd
(struct phy_device *phydev, int devad, u32 regnum)¶ Convenience function for reading a register from an MMD on a given PHY.
Parameters
struct phy_device *phydev
The phy_device struct
int devad
The MMD to read from (0..31)
u32 regnum
The register on the MMD to read (0..65535)
Description
Same rules as for __phy_read();
-
int
phy_read_mmd
(struct phy_device *phydev, int devad, u32 regnum)¶ Convenience function for reading a register from an MMD on a given PHY.
Parameters
struct phy_device *phydev
The phy_device struct
int devad
The MMD to read from
u32 regnum
The register on the MMD to read
Description
Same rules as for phy_read();
-
int
__phy_write_mmd
(struct phy_device *phydev, int devad, u32 regnum, u16 val)¶ Convenience function for writing a register on an MMD on a given PHY.
Parameters
struct phy_device *phydev
The phy_device struct
int devad
The MMD to read from
u32 regnum
The register on the MMD to read
u16 val
value to write to regnum
Description
Same rules as for __phy_write();
-
int
phy_write_mmd
(struct phy_device *phydev, int devad, u32 regnum, u16 val)¶ Convenience function for writing a register on an MMD on a given PHY.
Parameters
struct phy_device *phydev
The phy_device struct
int devad
The MMD to read from
u32 regnum
The register on the MMD to read
u16 val
value to write to regnum
Description
Same rules as for phy_write();
-
int
phy_modify_changed
(struct phy_device *phydev, u32 regnum, u16 mask, u16 set)¶ Function for modifying a PHY register
Parameters
struct phy_device *phydev
the phy_device struct
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
Description
Returns negative errno, 0 if there was no change, and 1 in case of change
-
int
__phy_modify
(struct phy_device *phydev, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a PHY register
Parameters
struct phy_device *phydev
the phy_device struct
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
phy_modify
(struct phy_device *phydev, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a given PHY register
Parameters
struct phy_device *phydev
the phy_device struct
u32 regnum
register number to write
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
__phy_modify_mmd_changed
(struct phy_device *phydev, int devad, u32 regnum, u16 mask, u16 set)¶ Function for modifying a register on MMD
Parameters
struct phy_device *phydev
the phy_device struct
int devad
the MMD containing register to modify
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
Description
Unlocked helper function which allows a MMD register to be modified as new register value = (old register value & ~mask) | set
Returns negative errno, 0 if there was no change, and 1 in case of change
-
int
phy_modify_mmd_changed
(struct phy_device *phydev, int devad, u32 regnum, u16 mask, u16 set)¶ Function for modifying a register on MMD
Parameters
struct phy_device *phydev
the phy_device struct
int devad
the MMD containing register to modify
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
Description
Returns negative errno, 0 if there was no change, and 1 in case of change
-
int
__phy_modify_mmd
(struct phy_device *phydev, int devad, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a register on MMD
Parameters
struct phy_device *phydev
the phy_device struct
int devad
the MMD containing register to modify
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
phy_modify_mmd
(struct phy_device *phydev, int devad, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a register on MMD
Parameters
struct phy_device *phydev
the phy_device struct
int devad
the MMD containing register to modify
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
new value of bits set in mask to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
phy_save_page
(struct phy_device *phydev)¶ take the bus lock and save the current page
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
Description
Take the MDIO bus lock, and return the current page number. On error,
returns a negative errno. phy_restore_page()
must always be called
after this, irrespective of success or failure of this call.
-
int
phy_select_page
(struct phy_device *phydev, int page)¶ take the bus lock, save the current page, and set a page
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int page
desired page
Description
Take the MDIO bus lock to protect against concurrent access, save the
current PHY page, and set the current page. On error, returns a
negative errno, otherwise returns the previous page number.
phy_restore_page()
must always be called after this, irrespective
of success or failure of this call.
-
int
phy_restore_page
(struct phy_device *phydev, int oldpage, int ret)¶ restore the page register and release the bus lock
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int oldpage
the old page, return value from
phy_save_page()
orphy_select_page()
int ret
operation’s return code
Description
Release the MDIO bus lock, restoring oldpage if it is a valid page. This function propagates the earliest error code from the group of operations.
Return
oldpage if it was a negative value, otherwise ret if it was a negative errno value, otherwise phy_write_page()’s negative value if it were in error, otherwise ret.
-
int
phy_read_paged
(struct phy_device *phydev, int page, u32 regnum)¶ Convenience function for reading a paged register
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int page
the page for the phy
u32 regnum
register number
Description
Same rules as for phy_read().
-
int
phy_write_paged
(struct phy_device *phydev, int page, u32 regnum, u16 val)¶ Convenience function for writing a paged register
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int page
the page for the phy
u32 regnum
register number
u16 val
value to write
Description
Same rules as for phy_write().
-
int
phy_modify_paged_changed
(struct phy_device *phydev, int page, u32 regnum, u16 mask, u16 set)¶ Function for modifying a paged register
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int page
the page for the phy
u32 regnum
register number
u16 mask
bit mask of bits to clear
u16 set
bit mask of bits to set
Description
Returns negative errno, 0 if there was no change, and 1 in case of change
-
int
phy_modify_paged
(struct phy_device *phydev, int page, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a paged register
Parameters
struct phy_device *phydev
a pointer to a
struct phy_device
int page
the page for the phy
u32 regnum
register number
u16 mask
bit mask of bits to clear
u16 set
bit mask of bits to set
Description
Same rules as for phy_read() and phy_write().
-
int
genphy_c45_pma_resume
(struct phy_device *phydev)¶ wakes up the PMA module
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_c45_pma_suspend
(struct phy_device *phydev)¶ suspends the PMA module
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_c45_pma_setup_forced
(struct phy_device *phydev)¶ configures a forced speed
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_c45_an_config_aneg
(struct phy_device *phydev)¶ configure advertisement registers
Parameters
struct phy_device *phydev
target phy_device struct
Description
Configure advertisement registers based on modes set in phydev->advertising
Returns negative errno code on failure, 0 if advertisement didn’t change, or 1 if advertised modes changed.
-
int
genphy_c45_an_disable_aneg
(struct phy_device *phydev)¶ disable auto-negotiation
Parameters
struct phy_device *phydev
target phy_device struct
Description
Disable auto-negotiation in the Clause 45 PHY. The link parameters are controlled through the PMA/PMD MMD registers.
Returns zero on success, negative errno code on failure.
-
int
genphy_c45_restart_aneg
(struct phy_device *phydev)¶ Enable and restart auto-negotiation
Parameters
struct phy_device *phydev
target phy_device struct
Description
This assumes that the auto-negotiation MMD is present.
Enable and restart auto-negotiation.
-
int
genphy_c45_check_and_restart_aneg
(struct phy_device *phydev, bool restart)¶ Enable and restart auto-negotiation
Parameters
struct phy_device *phydev
target phy_device struct
bool restart
whether aneg restart is requested
Description
This assumes that the auto-negotiation MMD is present.
Check, and restart auto-negotiation if needed.
-
int
genphy_c45_aneg_done
(struct phy_device *phydev)¶ return auto-negotiation complete status
Parameters
struct phy_device *phydev
target phy_device struct
Description
This assumes that the auto-negotiation MMD is present.
Reads the status register from the auto-negotiation MMD, returning: - positive if auto-negotiation is complete - negative errno code on error - zero otherwise
-
int
genphy_c45_read_link
(struct phy_device *phydev)¶ read the overall link status from the MMDs
Parameters
struct phy_device *phydev
target phy_device struct
Description
Read the link status from the specified MMDs, and if they all indicate that the link is up, set phydev->link to 1. If an error is encountered, a negative errno will be returned, otherwise zero.
-
int
genphy_c45_read_lpa
(struct phy_device *phydev)¶ read the link partner advertisement and pause
Parameters
struct phy_device *phydev
target phy_device struct
Description
Read the Clause 45 defined base (7.19) and 10G (7.33) status registers, filling in the link partner advertisement, pause and asym_pause members in phydev. This assumes that the auto-negotiation MMD is present, and the backplane bit (7.48.0) is clear. Clause 45 PHY drivers are expected to fill in the remainder of the link partner advert from vendor registers.
-
int
genphy_c45_read_pma
(struct phy_device *phydev)¶ read link speed etc from PMA
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_c45_read_mdix
(struct phy_device *phydev)¶ read mdix status from PMA
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_c45_pma_read_abilities
(struct phy_device *phydev)¶ read supported link modes from PMA
Parameters
struct phy_device *phydev
target phy_device struct
Description
Read the supported link modes from the PMA Status 2 (1.8) register. If bit 1.8.9 is set, the list of supported modes is build using the values in the PMA Extended Abilities (1.11) register, indicating 1000BASET an 10G related modes. If bit 1.11.14 is set, then the list is also extended with the modes in the 2.5G/5G PMA Extended register (1.21), indicating if 2.5GBASET and 5GBASET are supported.
-
int
genphy_c45_read_status
(struct phy_device *phydev)¶ read PHY status
Parameters
struct phy_device *phydev
target phy_device struct
Description
Reads status from PHY and sets phy_device members accordingly.
-
int
genphy_c45_config_aneg
(struct phy_device *phydev)¶ restart auto-negotiation or forced setup
Parameters
struct phy_device *phydev
target phy_device struct
Description
- If auto-negotiation is enabled, we configure the
advertising, and then restart auto-negotiation. If it is not enabled, then we force a configuration.
Error
kernel-doc missing
-
int
phy_register_fixup
(const char *bus_id, u32 phy_uid, u32 phy_uid_mask, int (*run)(struct phy_device *))¶ creates a new phy_fixup and adds it to the list
Parameters
const char *bus_id
A string which matches phydev->mdio.dev.bus_id (or PHY_ANY_ID)
u32 phy_uid
Used to match against phydev->phy_id (the UID of the PHY) It can also be PHY_ANY_UID
u32 phy_uid_mask
Applied to phydev->phy_id and fixup->phy_uid before comparison
int (*run)(struct phy_device *)
The actual code to be run when a matching PHY is found
-
int
phy_unregister_fixup
(const char *bus_id, u32 phy_uid, u32 phy_uid_mask)¶ remove a phy_fixup from the list
Parameters
const char *bus_id
A string matches fixup->bus_id (or PHY_ANY_ID) in phy_fixup_list
u32 phy_uid
A phy id matches fixup->phy_id (or PHY_ANY_UID) in phy_fixup_list
u32 phy_uid_mask
Applied to phy_uid and fixup->phy_uid before comparison
-
struct phy_device *
get_phy_device
(struct mii_bus *bus, int addr, bool is_c45)¶ reads the specified PHY device and returns its phy_device struct
Parameters
struct mii_bus *bus
the target MII bus
int addr
PHY address on the MII bus
bool is_c45
If true the PHY uses the 802.3 clause 45 protocol
Description
Probe for a PHY at addr on bus.
When probing for a clause 22 PHY, then read the ID registers. If we find
a valid ID, allocate and return a struct phy_device
.
When probing for a clause 45 PHY, read the “devices in package” registers.
If the “devices in package” appears valid, read the ID registers for each
MMD, allocate and return a struct phy_device
.
Returns an allocated struct phy_device
on success, -ENODEV
if there is
no PHY present, or -EIO
on bus access error.
-
int
phy_device_register
(struct phy_device *phydev)¶ Register the phy device on the MDIO bus
Parameters
struct phy_device *phydev
phy_device structure to be added to the MDIO bus
-
void
phy_device_remove
(struct phy_device *phydev)¶ Remove a previously registered phy device from the MDIO bus
Parameters
struct phy_device *phydev
phy_device structure to remove
Description
This doesn’t free the phy_device itself, it merely reverses the effects
of phy_device_register()
. Use phy_device_free() to free the device
after calling this function.
-
int
phy_get_c45_ids
(struct phy_device *phydev)¶ Read 802.3-c45 IDs for phy device.
Parameters
struct phy_device *phydev
phy_device structure to read 802.3-c45 IDs
Description
Returns zero on success, -EIO
on bus access error, or -ENODEV
if
the “devices in package” is invalid.
-
struct phy_device *
phy_find_first
(struct mii_bus *bus)¶ finds the first PHY device on the bus
Parameters
struct mii_bus *bus
the target MII bus
-
int
phy_connect_direct
(struct net_device *dev, struct phy_device *phydev, void (*handler)(struct net_device *), phy_interface_t interface)¶ connect an ethernet device to a specific phy_device
Parameters
struct net_device *dev
the network device to connect
struct phy_device *phydev
the pointer to the phy device
void (*handler)(struct net_device *)
callback function for state change notifications
phy_interface_t interface
PHY device’s interface
-
struct phy_device *
phy_connect
(struct net_device *dev, const char *bus_id, void (*handler)(struct net_device *), phy_interface_t interface)¶ connect an ethernet device to a PHY device
Parameters
struct net_device *dev
the network device to connect
const char *bus_id
the id string of the PHY device to connect
void (*handler)(struct net_device *)
callback function for state change notifications
phy_interface_t interface
PHY device’s interface
Description
- Convenience function for connecting ethernet
devices to PHY devices. The default behavior is for the PHY infrastructure to handle everything, and only notify the connected driver when the link status changes. If you don’t want, or can’t use the provided functionality, you may choose to call only the subset of functions which provide the desired functionality.
-
void
phy_disconnect
(struct phy_device *phydev)¶ disable interrupts, stop state machine, and detach a PHY device
Parameters
struct phy_device *phydev
target phy_device struct
-
void
phy_sfp_attach
(void *upstream, struct sfp_bus *bus)¶ attach the SFP bus to the PHY upstream network device
Parameters
void *upstream
pointer to the phy device
struct sfp_bus *bus
sfp bus representing cage being attached
Description
This is used to fill in the sfp_upstream_ops .attach member.
-
void
phy_sfp_detach
(void *upstream, struct sfp_bus *bus)¶ detach the SFP bus from the PHY upstream network device
Parameters
void *upstream
pointer to the phy device
struct sfp_bus *bus
sfp bus representing cage being attached
Description
This is used to fill in the sfp_upstream_ops .detach member.
-
int
phy_sfp_probe
(struct phy_device *phydev, const struct sfp_upstream_ops *ops)¶ probe for a SFP cage attached to this PHY device
Parameters
struct phy_device *phydev
Pointer to phy_device
const struct sfp_upstream_ops *ops
SFP’s upstream operations
-
int
phy_attach_direct
(struct net_device *dev, struct phy_device *phydev, u32 flags, phy_interface_t interface)¶ attach a network device to a given PHY device pointer
Parameters
struct net_device *dev
network device to attach
struct phy_device *phydev
Pointer to phy_device to attach
u32 flags
PHY device’s dev_flags
phy_interface_t interface
PHY device’s interface
Description
- Called by drivers to attach to a particular PHY
device. The phy_device is found, and properly hooked up to the phy_driver. If no driver is attached, then a generic driver is used. The phy_device is given a ptr to the attaching device, and given a callback for link status change. The phy_device is returned to the attaching driver. This function takes a reference on the phy device.
-
struct phy_device *
phy_attach
(struct net_device *dev, const char *bus_id, phy_interface_t interface)¶ attach a network device to a particular PHY device
Parameters
struct net_device *dev
network device to attach
const char *bus_id
Bus ID of PHY device to attach
phy_interface_t interface
PHY device’s interface
Description
- Same as phy_attach_direct() except that a PHY bus_id
string is passed instead of a pointer to a struct phy_device.
-
int
phy_package_join
(struct phy_device *phydev, int addr, size_t priv_size)¶ join a common PHY group
Parameters
struct phy_device *phydev
target phy_device struct
int addr
cookie and PHY address for global register access
size_t priv_size
if non-zero allocate this amount of bytes for private data
Description
This joins a PHY group and provides a shared storage for all phydevs in this group. This is intended to be used for packages which contain more than one PHY, for example a quad PHY transceiver.
The addr parameter serves as a cookie which has to have the same value for all members of one group and as a PHY address to access generic registers of a PHY package. Usually, one of the PHY addresses of the different PHYs in the package provides access to these global registers. The address which is given here, will be used in the phy_package_read() and phy_package_write() convenience functions. If your PHY doesn’t have global registers you can just pick any of the PHY addresses.
This will set the shared pointer of the phydev to the shared storage. If this is the first call for a this cookie the shared storage will be allocated. If priv_size is non-zero, the given amount of bytes are allocated for the priv member.
Returns < 1 on error, 0 on success. Esp. calling phy_package_join()
with the same cookie but a different priv_size is an error.
-
void
phy_package_leave
(struct phy_device *phydev)¶ leave a common PHY group
Parameters
struct phy_device *phydev
target phy_device struct
Description
This leaves a PHY group created by phy_package_join()
. If this phydev
was the last user of the shared data between the group, this data is
freed. Resets the phydev->shared pointer to NULL.
-
int
devm_phy_package_join
(struct device *dev, struct phy_device *phydev, int addr, size_t priv_size)¶ resource managed
phy_package_join()
Parameters
struct device *dev
device that is registering this PHY package
struct phy_device *phydev
target phy_device struct
int addr
cookie and PHY address for global register access
size_t priv_size
if non-zero allocate this amount of bytes for private data
Description
Managed phy_package_join()
. Shared storage fetched by this function,
phy_package_leave()
is automatically called on driver detach. See
phy_package_join()
for more information.
-
void
phy_detach
(struct phy_device *phydev)¶ detach a PHY device from its network device
Parameters
struct phy_device *phydev
target phy_device struct
Description
This detaches the phy device from its network device and the phy
driver, and drops the reference count taken in phy_attach_direct()
.
-
int
phy_reset_after_clk_enable
(struct phy_device *phydev)¶ perform a PHY reset if needed
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Some PHYs are known to need a reset after their refclk was
enabled. This function evaluates the flags and perform the reset if it’s needed. Returns < 0 on error, 0 if the phy wasn’t reset and 1 if the phy was reset.
-
int
genphy_config_eee_advert
(struct phy_device *phydev)¶ disable unwanted eee mode advertisement
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Writes MDIO_AN_EEE_ADV after disabling unsupported energy
efficent ethernet modes. Returns 0 if the PHY’s advertisement hasn’t changed, and 1 if it has changed.
-
int
genphy_setup_forced
(struct phy_device *phydev)¶ configures/forces speed/duplex from phydev
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Configures MII_BMCR to force speed/duplex
to the values in phydev. Assumes that the values are valid. Please see
phy_sanitize_settings()
.
-
int
genphy_restart_aneg
(struct phy_device *phydev)¶ Enable and Restart Autonegotiation
Parameters
struct phy_device *phydev
target phy_device struct
-
int
genphy_check_and_restart_aneg
(struct phy_device *phydev, bool restart)¶ Enable and restart auto-negotiation
Parameters
struct phy_device *phydev
target phy_device struct
bool restart
whether aneg restart is requested
Description
Check, and restart auto-negotiation if needed.
-
int
__genphy_config_aneg
(struct phy_device *phydev, bool changed)¶ restart auto-negotiation or write BMCR
Parameters
struct phy_device *phydev
target phy_device struct
bool changed
whether autoneg is requested
Description
- If auto-negotiation is enabled, we configure the
advertising, and then restart auto-negotiation. If it is not enabled, then we write the BMCR.
-
int
genphy_c37_config_aneg
(struct phy_device *phydev)¶ restart auto-negotiation or write BMCR
Parameters
struct phy_device *phydev
target phy_device struct
Description
- If auto-negotiation is enabled, we configure the
advertising, and then restart auto-negotiation. If it is not enabled, then we write the BMCR. This function is intended for use with Clause 37 1000Base-X mode.
-
int
genphy_aneg_done
(struct phy_device *phydev)¶ return auto-negotiation status
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Reads the status register and returns 0 either if
auto-negotiation is incomplete, or if there was an error. Returns BMSR_ANEGCOMPLETE if auto-negotiation is done.
-
int
genphy_update_link
(struct phy_device *phydev)¶ update link status in phydev
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Update the value in phydev->link to reflect the
current link value. In order to do this, we need to read the status register twice, keeping the second value.
-
int
genphy_read_status_fixed
(struct phy_device *phydev)¶ read the link parameters for !aneg mode
Parameters
struct phy_device *phydev
target phy_device struct
Description
Read the current duplex and speed state for a PHY operating with autonegotiation disabled.
-
int
genphy_read_status
(struct phy_device *phydev)¶ check the link status and update current link state
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Check the link, then figure out the current state
by comparing what we advertise with what the link partner advertises. Start by checking the gigabit possibilities, then move on to 10/100.
-
int
genphy_c37_read_status
(struct phy_device *phydev)¶ check the link status and update current link state
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Check the link, then figure out the current state
by comparing what we advertise with what the link partner advertises. This function is for Clause 37 1000Base-X mode.
-
int
genphy_soft_reset
(struct phy_device *phydev)¶ software reset the PHY via BMCR_RESET bit
Parameters
struct phy_device *phydev
target phy_device struct
Description
Perform a software PHY reset using the standard BMCR_RESET bit and poll for the reset bit to be cleared.
Return
0 on success, < 0 on failure
-
int
genphy_read_abilities
(struct phy_device *phydev)¶ read PHY abilities from Clause 22 registers
Parameters
struct phy_device *phydev
target phy_device struct
Description
Reads the PHY’s abilities and populates phydev->supported accordingly.
Return
0 on success, < 0 on failure
-
void
phy_remove_link_mode
(struct phy_device *phydev, u32 link_mode)¶ Remove a supported link mode
Parameters
struct phy_device *phydev
phy_device structure to remove link mode from
u32 link_mode
Link mode to be removed
Description
Some MACs don’t support all link modes which the PHY does. e.g. a 1G MAC often does not support 1000Half. Add a helper to remove a link mode.
-
void
phy_advertise_supported
(struct phy_device *phydev)¶ Advertise all supported modes
Parameters
struct phy_device *phydev
target phy_device struct
Description
Called to advertise all supported modes, doesn’t touch pause mode advertising.
-
void
phy_support_sym_pause
(struct phy_device *phydev)¶ Enable support of symmetrical pause
Parameters
struct phy_device *phydev
target phy_device struct
Description
Called by the MAC to indicate is supports symmetrical Pause, but not asym pause.
-
void
phy_support_asym_pause
(struct phy_device *phydev)¶ Enable support of asym pause
Parameters
struct phy_device *phydev
target phy_device struct
Description
Called by the MAC to indicate is supports Asym Pause.
-
void
phy_set_sym_pause
(struct phy_device *phydev, bool rx, bool tx, bool autoneg)¶ Configure symmetric Pause
Parameters
struct phy_device *phydev
target phy_device struct
bool rx
Receiver Pause is supported
bool tx
Transmit Pause is supported
bool autoneg
Auto neg should be used
Description
Configure advertised Pause support depending on if receiver pause and pause auto neg is supported. Generally called from the set_pauseparam .ndo.
-
void
phy_set_asym_pause
(struct phy_device *phydev, bool rx, bool tx)¶ Configure Pause and Asym Pause
Parameters
struct phy_device *phydev
target phy_device struct
bool rx
Receiver Pause is supported
bool tx
Transmit Pause is supported
Description
Configure advertised Pause support depending on if transmit and receiver pause is supported. If there has been a change in adverting, trigger a new autoneg. Generally called from the set_pauseparam .ndo.
-
bool
phy_validate_pause
(struct phy_device *phydev, struct ethtool_pauseparam *pp)¶ Test if the PHY/MAC support the pause configuration
Parameters
struct phy_device *phydev
phy_device struct
struct ethtool_pauseparam *pp
requested pause configuration
Description
Test if the PHY/MAC combination supports the Pause configuration the user is requesting. Returns True if it is supported, false otherwise.
-
void
phy_get_pause
(struct phy_device *phydev, bool *tx_pause, bool *rx_pause)¶ resolve negotiated pause modes
Parameters
struct phy_device *phydev
phy_device struct
bool *tx_pause
pointer to bool to indicate whether transmit pause should be enabled.
bool *rx_pause
pointer to bool to indicate whether receive pause should be enabled.
Description
Resolve and return the flow control modes according to the negotiation result. This includes checking that we are operating in full duplex mode. See linkmode_resolve_pause() for further details.
-
s32
phy_get_internal_delay
(struct phy_device *phydev, struct device *dev, const int *delay_values, int size, bool is_rx)¶ returns the index of the internal delay
Parameters
struct phy_device *phydev
phy_device struct
struct device *dev
pointer to the devices device struct
const int *delay_values
array of delays the PHY supports
int size
the size of the delay array
bool is_rx
boolean to indicate to get the rx internal delay
Description
Returns the index within the array of internal delay passed in. If the device property is not present then the interface type is checked if the interface defines use of internal delay then a 1 is returned otherwise a 0 is returned. The array must be in ascending order. If PHY does not have an ascending order array then size = 0 and the value of the delay property is returned. Return -EINVAL if the delay is invalid or cannot be found.
-
struct mdio_device *
fwnode_mdio_find_device
(struct fwnode_handle *fwnode)¶ Given a fwnode, find the mdio_device
Parameters
struct fwnode_handle *fwnode
pointer to the mdio_device’s fwnode
Description
If successful, returns a pointer to the mdio_device with the embedded
struct device refcount incremented by one, or NULL on failure.
The caller should call put_device()
on the mdio_device after its use.
-
struct phy_device *
fwnode_phy_find_device
(struct fwnode_handle *phy_fwnode)¶ For provided phy_fwnode, find phy_device.
Parameters
struct fwnode_handle *phy_fwnode
Pointer to the phy’s fwnode.
Description
If successful, returns a pointer to the phy_device with the embedded struct device refcount incremented by one, or NULL on failure.
-
struct phy_device *
device_phy_find_device
(struct device *dev)¶ For the given device, get the phy_device
Parameters
struct device *dev
Pointer to the given device
Description
Refer return conditions of fwnode_phy_find_device()
.
-
struct fwnode_handle *
fwnode_get_phy_node
(struct fwnode_handle *fwnode)¶ Get the phy_node using the named reference.
Parameters
struct fwnode_handle *fwnode
Pointer to fwnode from which phy_node has to be obtained.
Description
Refer return conditions of fwnode_find_reference(). For ACPI, only “phy-handle” is supported. Legacy DT properties “phy” and “phy-device” are not supported in ACPI. DT supports all the three named references to the phy node.
-
int
phy_driver_register
(struct phy_driver *new_driver, struct module *owner)¶ register a phy_driver with the PHY layer
Parameters
struct phy_driver *new_driver
new phy_driver to register
struct module *owner
module owning this PHY
-
int
get_phy_c45_ids
(struct mii_bus *bus, int addr, struct phy_c45_device_ids *c45_ids)¶ reads the specified addr for its 802.3-c45 IDs.
Parameters
struct mii_bus *bus
the target MII bus
int addr
PHY address on the MII bus
struct phy_c45_device_ids *c45_ids
where to store the c45 ID information.
Description
Read the PHY “devices in package”. If this appears to be valid, read the PHY identifiers for each device. Return the “devices in package” and identifiers in c45_ids.
Returns zero on success, -EIO
on bus access error, or -ENODEV
if
the “devices in package” is invalid.
-
int
get_phy_c22_id
(struct mii_bus *bus, int addr, u32 *phy_id)¶ reads the specified addr for its clause 22 ID.
Parameters
struct mii_bus *bus
the target MII bus
int addr
PHY address on the MII bus
u32 *phy_id
where to store the ID retrieved.
Description
Read the 802.3 clause 22 PHY ID from the PHY at addr on the bus,
placing it in phy_id. Return zero on successful read and the ID is
valid, -EIO
on bus access error, or -ENODEV
if no device responds
or invalid ID.
-
void
phy_prepare_link
(struct phy_device *phydev, void (*handler)(struct net_device *))¶ prepares the PHY layer to monitor link status
Parameters
struct phy_device *phydev
target phy_device struct
void (*handler)(struct net_device *)
callback function for link status change notifications
Description
- Tells the PHY infrastructure to handle the
gory details on monitoring link status (whether through polling or an interrupt), and to call back to the connected device driver when the link status changes. If you want to monitor your own link state, don’t call this function.
-
int
phy_poll_reset
(struct phy_device *phydev)¶ Safely wait until a PHY reset has properly completed
Parameters
struct phy_device *phydev
The PHY device to poll
Description
- According to IEEE 802.3, Section 2, Subsection 22.2.4.1.1, as
published in 2008, a PHY reset may take up to 0.5 seconds. The MII BMCR register must be polled until the BMCR_RESET bit clears.
Furthermore, any attempts to write to PHY registers may have no effect or even generate MDIO bus errors until this is complete.
Some PHYs (such as the Marvell 88E1111) don’t entirely conform to the standard and do not fully reset after the BMCR_RESET bit is set, and may even REQUIRE a soft-reset to properly restart autonegotiation. In an effort to support such broken PHYs, this function is separate from the standard phy_init_hw() which will zero all the other bits in the BMCR and reapply all driver-specific and board-specific fixups.
-
int
genphy_config_advert
(struct phy_device *phydev)¶ sanitize and advertise auto-negotiation parameters
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Writes MII_ADVERTISE with the appropriate values,
after sanitizing the values to make sure we only advertise what is supported. Returns < 0 on error, 0 if the PHY’s advertisement hasn’t changed, and > 0 if it has changed.
-
int
genphy_c37_config_advert
(struct phy_device *phydev)¶ sanitize and advertise auto-negotiation parameters
Parameters
struct phy_device *phydev
target phy_device struct
Description
- Writes MII_ADVERTISE with the appropriate values,
after sanitizing the values to make sure we only advertise what is supported. Returns < 0 on error, 0 if the PHY’s advertisement hasn’t changed, and > 0 if it has changed. This function is intended for Clause 37 1000Base-X mode.
-
int
phy_probe
(struct device *dev)¶ probe and init a PHY device
Parameters
struct device *dev
device to probe and init
Description
- Take care of setting up the phy_device structure,
set the state to READY (the driver’s init function should set it to STARTING if needed).
-
struct mii_bus *
mdiobus_alloc_size
(size_t size)¶ allocate a mii_bus structure
Parameters
size_t size
extra amount of memory to allocate for private storage. If non-zero, then bus->priv is points to that memory.
Description
called by a bus driver to allocate an mii_bus structure to fill in.
-
struct mii_bus *
mdio_find_bus
(const char *mdio_name)¶ Given the name of a mdiobus, find the mii_bus.
Parameters
const char *mdio_name
The name of a mdiobus.
Description
Returns a reference to the mii_bus, or NULL if none found. The embedded struct device will have its reference count incremented, and this must be put_deviced’ed once the bus is finished with.
-
struct mii_bus *
of_mdio_find_bus
(struct device_node *mdio_bus_np)¶ Given an mii_bus node, find the mii_bus.
Parameters
struct device_node *mdio_bus_np
Pointer to the mii_bus.
Description
Returns a reference to the mii_bus, or NULL if none found. The embedded struct device will have its reference count incremented, and this must be put once the bus is finished with.
Because the association of a device_node and mii_bus is made via of_mdiobus_register(), the mii_bus cannot be found before it is registered with of_mdiobus_register().
-
int
__mdiobus_register
(struct mii_bus *bus, struct module *owner)¶ bring up all the PHYs on a given bus and attach them to bus
Parameters
struct mii_bus *bus
target mii_bus
struct module *owner
module containing bus accessor functions
Description
- Called by a bus driver to bring up all the PHYs
on a given bus, and attach them to the bus. Drivers should use mdiobus_register() rather than
__mdiobus_register()
unless they need to pass a specific owner module. MDIO devices which are not PHYs will not be brought up by this function. They are expected to be explicitly listed in DT and instantiated by of_mdiobus_register().
Returns 0 on success or < 0 on error.
-
void
mdiobus_free
(struct mii_bus *bus)¶ free a struct mii_bus
Parameters
struct mii_bus *bus
mii_bus to free
Description
This function releases the reference to the underlying device object in the mii_bus. If this is the last reference, the mii_bus will be freed.
-
struct phy_device *
mdiobus_scan
(struct mii_bus *bus, int addr)¶ scan a bus for MDIO devices.
Parameters
struct mii_bus *bus
mii_bus to scan
int addr
address on bus to scan
Description
This function scans the MDIO bus, looking for devices which can be identified using a vendor/product ID in registers 2 and 3. Not all MDIO devices have such registers, but PHY devices typically do. Hence this function assumes anything found is a PHY, or can be treated as a PHY. Other MDIO devices, such as switches, will probably not be found during the scan.
-
int
__mdiobus_read
(struct mii_bus *bus, int addr, u32 regnum)¶ Unlocked version of the mdiobus_read function
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to read
Description
Read a MDIO bus register. Caller must hold the mdio bus lock.
NOTE
MUST NOT be called from interrupt context.
-
int
__mdiobus_write
(struct mii_bus *bus, int addr, u32 regnum, u16 val)¶ Unlocked version of the mdiobus_write function
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to write
u16 val
value to write to regnum
Description
Write a MDIO bus register. Caller must hold the mdio bus lock.
NOTE
MUST NOT be called from interrupt context.
-
int
__mdiobus_modify_changed
(struct mii_bus *bus, int addr, u32 regnum, u16 mask, u16 set)¶ Unlocked version of the mdiobus_modify function
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to modify
u16 mask
bit mask of bits to clear
u16 set
bit mask of bits to set
Description
Read, modify, and if any change, write the register value back to the device. Any error returns a negative number.
NOTE
MUST NOT be called from interrupt context.
-
int
mdiobus_read_nested
(struct mii_bus *bus, int addr, u32 regnum)¶ Nested version of the mdiobus_read function
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to read
Description
In case of nested MDIO bus access avoid lockdep false positives by using mutex_lock_nested().
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
mdiobus_read
(struct mii_bus *bus, int addr, u32 regnum)¶ Convenience function for reading a given MII mgmt register
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to read
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
mdiobus_write_nested
(struct mii_bus *bus, int addr, u32 regnum, u16 val)¶ Nested version of the mdiobus_write function
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to write
u16 val
value to write to regnum
Description
In case of nested MDIO bus access avoid lockdep false positives by using mutex_lock_nested().
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
mdiobus_write
(struct mii_bus *bus, int addr, u32 regnum, u16 val)¶ Convenience function for writing a given MII mgmt register
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to write
u16 val
value to write to regnum
NOTE
MUST NOT be called from interrupt context, because the bus read/write functions may wait for an interrupt to conclude the operation.
-
int
mdiobus_modify
(struct mii_bus *bus, int addr, u32 regnum, u16 mask, u16 set)¶ Convenience function for modifying a given mdio device register
Parameters
struct mii_bus *bus
the mii_bus struct
int addr
the phy address
u32 regnum
register number to write
u16 mask
bit mask of bits to clear
u16 set
bit mask of bits to set
-
void
mdiobus_release
(struct device *d)¶ mii_bus device release callback
Parameters
struct device *d
the target struct device that contains the mii_bus
Description
called when the last reference to an mii_bus is dropped, to free the underlying memory.
-
int
mdiobus_create_device
(struct mii_bus *bus, struct mdio_board_info *bi)¶ create a full MDIO device given a mdio_board_info structure
Parameters
struct mii_bus *bus
MDIO bus to create the devices on
struct mdio_board_info *bi
mdio_board_info structure describing the devices
Description
Returns 0 on success or < 0 on error.
-
int
mdio_bus_match
(struct device *dev, struct device_driver *drv)¶ determine if given MDIO driver supports the given MDIO device
Parameters
struct device *dev
target MDIO device
struct device_driver *drv
given MDIO driver
Description
- Given a MDIO device, and a MDIO driver, return 1 if
the driver supports the device. Otherwise, return 0. This may require calling the devices own match function, since different classes of MDIO devices have different match criteria.
PHYLINK¶
PHYLINK interfaces traditional network drivers with PHYLIB, fixed-links, and SFF modules (eg, hot-pluggable SFP) that may contain PHYs. PHYLINK provides management of the link state and link modes.
-
struct
phylink_link_state
¶ link state structure
Definition
struct phylink_link_state {
unsigned long advertising[BITS_TO_LONGS(__ETHTOOL_LINK_MODE_MASK_NBITS)];
unsigned long lp_advertising[BITS_TO_LONGS(__ETHTOOL_LINK_MODE_MASK_NBITS)];
phy_interface_t interface;
int speed;
int duplex;
int pause;
unsigned int link:1;
unsigned int an_enabled:1;
unsigned int an_complete:1;
};
Members
advertising
ethtool bitmask containing advertised link modes
lp_advertising
ethtool bitmask containing link partner advertised link modes
interface
link
typedef phy_interface_t
modespeed
link speed, one of the SPEED_* constants.
duplex
link duplex mode, one of DUPLEX_* constants.
pause
link pause state, described by MLO_PAUSE_* constants.
link
true if the link is up.
an_enabled
true if autonegotiation is enabled/desired.
an_complete
true if autonegotiation has completed.
-
struct
phylink_config
¶ PHYLINK configuration structure
Definition
struct phylink_config {
struct device *dev;
enum phylink_op_type type;
bool pcs_poll;
bool poll_fixed_state;
bool ovr_an_inband;
void (*get_fixed_state)(struct phylink_config *config, struct phylink_link_state *state);
};
Members
dev
a pointer to a struct device associated with the MAC
type
operation type of PHYLINK instance
pcs_poll
MAC PCS cannot provide link change interrupt
poll_fixed_state
if true, starts link_poll, if MAC link is at
MLO_AN_FIXED
mode.ovr_an_inband
if true, override PCS to MLO_AN_INBAND
get_fixed_state
callback to execute to determine the fixed link state, if MAC link is at
MLO_AN_FIXED
mode.
-
struct
phylink_mac_ops
¶ MAC operations structure.
Definition
struct phylink_mac_ops {
void (*validate)(struct phylink_config *config,unsigned long *supported, struct phylink_link_state *state);
void (*mac_pcs_get_state)(struct phylink_config *config, struct phylink_link_state *state);
int (*mac_prepare)(struct phylink_config *config, unsigned int mode, phy_interface_t iface);
void (*mac_config)(struct phylink_config *config, unsigned int mode, const struct phylink_link_state *state);
int (*mac_finish)(struct phylink_config *config, unsigned int mode, phy_interface_t iface);
void (*mac_an_restart)(struct phylink_config *config);
void (*mac_link_down)(struct phylink_config *config, unsigned int mode, phy_interface_t interface);
void (*mac_link_up)(struct phylink_config *config,struct phy_device *phy, unsigned int mode,phy_interface_t interface, int speed, int duplex, bool tx_pause, bool rx_pause);
};
Members
validate
Validate and update the link configuration.
mac_pcs_get_state
Read the current link state from the hardware.
mac_prepare
prepare for a major reconfiguration of the interface.
mac_config
configure the MAC for the selected mode and state.
mac_finish
finish a major reconfiguration of the interface.
mac_an_restart
restart 802.3z BaseX autonegotiation.
mac_link_down
take the link down.
mac_link_up
allow the link to come up.
Description
The individual methods are described more fully below.
-
void
validate
(struct phylink_config *config, unsigned long *supported, struct phylink_link_state *state)¶ Validate and update the link configuration
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.unsigned long *supported
ethtool bitmask for supported link modes.
struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.
Description
Clear bits in the supported and state->advertising masks that are not supportable by the MAC.
Note that the PHY may be able to transform from one connection
technology to another, so, eg, don’t clear 1000BaseX just
because the MAC is unable to BaseX mode. This is more about
clearing unsupported speeds and duplex settings. The port modes
should not be cleared; phylink_set_port_modes()
will help with this.
If the state->interface mode is PHY_INTERFACE_MODE_1000BASEX
or PHY_INTERFACE_MODE_2500BASEX
, select the appropriate mode
based on state->advertising and/or state->speed and update
state->interface accordingly. See phylink_helper_basex_speed()
.
When state->interface is PHY_INTERFACE_MODE_NA
, phylink expects the
MAC driver to return all supported link modes.
If the state->interface mode is not supported, then the supported mask must be cleared.
-
void
mac_pcs_get_state
(struct phylink_config *config, struct phylink_link_state *state)¶ Read the current inband link state from the hardware
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.
Description
Read the current inband link state from the MAC PCS, reporting the
current speed in state->speed, duplex mode in state->duplex, pause
mode in state->pause using the MLO_PAUSE_RX
and MLO_PAUSE_TX
bits,
negotiation completion state in state->an_complete, and link up state
in state->link. If possible, state->lp_advertising should also be
populated.
-
int
mac_prepare
(struct phylink_config *config, unsigned int mode, phy_interface_t iface)¶ prepare to change the PHY interface mode
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.unsigned int mode
one of
MLO_AN_FIXED
,MLO_AN_PHY
,MLO_AN_INBAND
.phy_interface_t iface
interface mode to switch to
Description
phylink will call this method at the beginning of a full initialisation of the link, which includes changing the interface mode or at initial startup time. It may be called for the current mode. The MAC driver should perform whatever actions are required, e.g. disabling the Serdes PHY.
This will be the first call in the sequence:
- mac_prepare()
- mac_config()
- pcs_config()
- possible pcs_an_restart()
- mac_finish()
Returns zero on success, or negative errno on failure which will be reported to the kernel log.
-
void
mac_config
(struct phylink_config *config, unsigned int mode, const struct phylink_link_state *state)¶ configure the MAC for the selected mode and state
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.unsigned int mode
one of
MLO_AN_FIXED
,MLO_AN_PHY
,MLO_AN_INBAND
.const struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.
Description
Note - not all members of state are valid. In particular,
state->lp_advertising, state->link, state->an_complete are never
guaranteed to be correct, and so any mac_config()
implementation must
never reference these fields.
- (this requires a rewrite - please refer to mac_link_up() for situations
where the PCS and MAC are not tightly integrated.)
In all negotiation modes, as defined by mode, state->pause indicates the
pause settings which should be applied as follows. If MLO_PAUSE_AN
is not
set, MLO_PAUSE_TX
and MLO_PAUSE_RX
indicate whether the MAC should send
pause frames and/or act on received pause frames respectively. Otherwise,
the results of in-band negotiation/status from the MAC PCS should be used
to control the MAC pause mode settings.
The action performed depends on the currently selected mode:
MLO_AN_FIXED
,MLO_AN_PHY
:Configure for non-inband negotiation mode, where the link settings are completely communicated via
mac_link_up()
. The physical link protocol from the MAC is specified by state->interface.state->advertising may be used, but is not required.
Older drivers (prior to the
mac_link_up()
change) may use state->speed, state->duplex and state->pause to configure the MAC, but this is deprecated; such drivers should be converted to usemac_link_up()
.Other members of state must be ignored.
Valid state members: interface, advertising. Deprecated state members: speed, duplex, pause.
MLO_AN_INBAND
:place the link in an inband negotiation mode (such as 802.3z 1000base-X or Cisco SGMII mode depending on the state->interface mode). In both cases, link state management (whether the link is up or not) is performed by the MAC, and reported via the
mac_pcs_get_state()
callback. Changes in link state must be made by callingphylink_mac_change()
.Interface mode specific details are mentioned below.
If in 802.3z mode, the link speed is fixed, dependent on the state->interface. Duplex and pause modes are negotiated via the in-band configuration word. Advertised pause modes are set according to the state->an_enabled and state->advertising flags. Beware of MACs which only support full duplex at gigabit and higher speeds.
If in Cisco SGMII mode, the link speed and duplex mode are passed in the serial bitstream 16-bit configuration word, and the MAC should be configured to read these bits and acknowledge the configuration word. Nothing is advertised by the MAC. The MAC is responsible for reading the configuration word and configuring itself accordingly.
Valid state members: interface, an_enabled, pause, advertising.
Implementations are expected to update the MAC to reflect the requested settings - i.o.w., if nothing has changed between two calls, no action is expected. If only flow control settings have changed, flow control should be updated without taking the link down. This “update” behaviour is critical to avoid bouncing the link up status.
-
int
mac_finish
(struct phylink_config *config, unsigned int mode, phy_interface_t iface)¶ finish a to change the PHY interface mode
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.unsigned int mode
one of
MLO_AN_FIXED
,MLO_AN_PHY
,MLO_AN_INBAND
.phy_interface_t iface
interface mode to switch to
Description
phylink will call this if it called mac_prepare()
to allow the MAC to
complete any necessary steps after the MAC and PCS have been configured
for the mode and iface. E.g. a MAC driver may wish to re-enable the
Serdes PHY here if it was previously disabled by mac_prepare()
.
Returns zero on success, or negative errno on failure which will be reported to the kernel log.
-
void
mac_an_restart
(struct phylink_config *config)¶ restart 802.3z BaseX autonegotiation
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.
-
void
mac_link_down
(struct phylink_config *config, unsigned int mode, phy_interface_t interface)¶ take the link down
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.unsigned int mode
link autonegotiation mode
phy_interface_t interface
link
typedef phy_interface_t
mode
Description
If mode is not an in-band negotiation mode (as defined by
phylink_autoneg_inband()), force the link down and disable any
Energy Efficient Ethernet MAC configuration. Interface type
selection must be done in mac_config()
.
-
void
mac_link_up
(struct phylink_config *config, struct phy_device *phy, unsigned int mode, phy_interface_t interface, int speed, int duplex, bool tx_pause, bool rx_pause)¶ allow the link to come up
Parameters
struct phylink_config *config
a pointer to a
struct phylink_config
.struct phy_device *phy
any attached phy
unsigned int mode
link autonegotiation mode
phy_interface_t interface
link
typedef phy_interface_t
modeint speed
link speed
int duplex
link duplex
bool tx_pause
link transmit pause enablement status
bool rx_pause
link receive pause enablement status
Description
Configure the MAC for an established link.
speed, duplex, tx_pause and rx_pause indicate the finalised link settings, and should be used to configure the MAC block appropriately where these settings are not automatically conveyed from the PCS block, or if in-band negotiation (as defined by phylink_autoneg_inband(mode)) is disabled.
Note that when 802.3z in-band negotiation is in use, it is possible that the user wishes to override the pause settings, and this should be allowed when considering the implementation of this method.
If in-band negotiation mode is disabled, allow the link to come up. If
phy is non-NULL
, configure Energy Efficient Ethernet by calling
phy_init_eee()
and perform appropriate MAC configuration for EEE.
Interface type selection must be done in mac_config()
.
-
struct
phylink_pcs
¶ PHYLINK PCS instance
Definition
struct phylink_pcs {
const struct phylink_pcs_ops *ops;
bool poll;
};
Members
ops
a pointer to the
struct phylink_pcs_ops
structurepoll
poll the PCS for link changes
Description
This structure is designed to be embedded within the PCS private data, and will be passed between phylink and the PCS.
-
struct
phylink_pcs_ops
¶ MAC PCS operations structure.
Definition
struct phylink_pcs_ops {
void (*pcs_get_state)(struct phylink_pcs *pcs, struct phylink_link_state *state);
int (*pcs_config)(struct phylink_pcs *pcs, unsigned int mode,phy_interface_t interface,const unsigned long *advertising, bool permit_pause_to_mac);
void (*pcs_an_restart)(struct phylink_pcs *pcs);
void (*pcs_link_up)(struct phylink_pcs *pcs, unsigned int mode, phy_interface_t interface, int speed, int duplex);
};
Members
pcs_get_state
read the current MAC PCS link state from the hardware.
pcs_config
configure the MAC PCS for the selected mode and state.
pcs_an_restart
restart 802.3z BaseX autonegotiation.
pcs_link_up
program the PCS for the resolved link configuration (where necessary).
-
void
pcs_get_state
(struct phylink_pcs *pcs, struct phylink_link_state *state)¶ Read the current inband link state from the hardware
Parameters
struct phylink_pcs *pcs
a pointer to a
struct phylink_pcs
.struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.
Description
Read the current inband link state from the MAC PCS, reporting the
current speed in state->speed, duplex mode in state->duplex, pause
mode in state->pause using the MLO_PAUSE_RX
and MLO_PAUSE_TX
bits,
negotiation completion state in state->an_complete, and link up state
in state->link. If possible, state->lp_advertising should also be
populated.
When present, this overrides mac_pcs_get_state()
in struct
phylink_mac_ops
.
-
int
pcs_config
(struct phylink_pcs *pcs, unsigned int mode, phy_interface_t interface, const unsigned long *advertising, bool permit_pause_to_mac)¶ Configure the PCS mode and advertisement
Parameters
struct phylink_pcs *pcs
a pointer to a
struct phylink_pcs
.unsigned int mode
one of
MLO_AN_FIXED
,MLO_AN_PHY
,MLO_AN_INBAND
.phy_interface_t interface
interface mode to be used
const unsigned long *advertising
adertisement ethtool link mode mask
bool permit_pause_to_mac
permit forwarding pause resolution to MAC
Description
Configure the PCS for the operating mode, the interface mode, and set the advertisement mask. permit_pause_to_mac indicates whether the hardware may forward the pause mode resolution to the MAC.
When operating in MLO_AN_INBAND
, inband should always be enabled,
otherwise inband should be disabled.
For SGMII, there is no advertisement from the MAC side, the PCS should be programmed to acknowledge the inband word from the PHY.
For 1000BASE-X, the advertisement should be programmed into the PCS.
For most 10GBASE-R, there is no advertisement.
-
void
pcs_an_restart
(struct phylink_pcs *pcs)¶ restart 802.3z BaseX autonegotiation
Parameters
struct phylink_pcs *pcs
a pointer to a
struct phylink_pcs
.
Description
When PCS ops are present, this overrides mac_an_restart()
in struct
phylink_mac_ops
.
-
void
pcs_link_up
(struct phylink_pcs *pcs, unsigned int mode, phy_interface_t interface, int speed, int duplex)¶ program the PCS for the resolved link configuration
Parameters
struct phylink_pcs *pcs
a pointer to a
struct phylink_pcs
.unsigned int mode
link autonegotiation mode
phy_interface_t interface
link
typedef phy_interface_t
modeint speed
link speed
int duplex
link duplex
Description
This call will be made just before mac_link_up()
to inform the PCS of
the resolved link parameters. For example, a PCS operating in SGMII
mode without in-band AN needs to be manually configured for the link
and duplex setting. Otherwise, this should be a no-op.
-
struct
phylink
¶ internal data type for phylink
Definition
struct phylink {
};
Members
-
void
phylink_set_port_modes
(unsigned long *mask)¶ set the port type modes in the ethtool mask
Parameters
unsigned long *mask
ethtool link mode mask
Description
Sets all the port type modes in the ethtool mask. MAC drivers should use this in their ‘validate’ callback.
-
struct phylink *
phylink_create
(struct phylink_config *config, struct fwnode_handle *fwnode, phy_interface_t iface, const struct phylink_mac_ops *mac_ops)¶ create a phylink instance
Parameters
struct phylink_config *config
a pointer to the target
struct phylink_config
struct fwnode_handle *fwnode
a pointer to a
struct fwnode_handle
describing the network interfacephy_interface_t iface
the desired link mode defined by
typedef phy_interface_t
const struct phylink_mac_ops *mac_ops
a pointer to a
struct phylink_mac_ops
for the MAC.
Description
Create a new phylink instance, and parse the link parameters found in np. This will parse in-band modes, fixed-link or SFP configuration.
Returns a pointer to a struct phylink
, or an error-pointer value. Users
must use IS_ERR() to check for errors from this function.
Note
the rtnl lock must not be held when calling this function.
-
void
phylink_set_pcs
(struct phylink *pl, struct phylink_pcs *pcs)¶ set the current PCS for phylink to use
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct phylink_pcs *pcs
a pointer to the
struct phylink_pcs
Description
Bind the MAC PCS to phylink. This may be called after phylink_create()
,
in mac_prepare()
or mac_config()
methods if it is desired to dynamically
change the PCS.
Please note that there are behavioural changes with the mac_config()
callback if a PCS is present (denoting a newer setup) so removing a PCS
is not supported, and if a PCS is going to be used, it must be registered
by calling phylink_set_pcs()
at the latest in the first mac_config()
call.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Destroy a phylink instance. Any PHY that has been attached must have been
cleaned up via phylink_disconnect_phy()
prior to calling this function.
Note
the rtnl lock must not be held when calling this function.
-
int
phylink_connect_phy
(struct phylink *pl, struct phy_device *phy)¶ connect a PHY to the phylink instance
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct phy_device *phy
a pointer to a
struct phy_device
.
Description
Connect phy to the phylink instance specified by pl by calling
phy_attach_direct()
. Configure the phy according to the MAC driver’s
capabilities, start the PHYLIB state machine and enable any interrupts
that the PHY supports.
This updates the phylink’s ethtool supported and advertising link mode masks.
Returns 0 on success or a negative errno.
-
int
phylink_of_phy_connect
(struct phylink *pl, struct device_node *dn, u32 flags)¶ connect the PHY specified in the DT mode.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct device_node *dn
a pointer to a
struct device_node
.u32 flags
PHY-specific flags to communicate to the PHY device driver
Description
Connect the phy specified in the device node dn to the phylink instance
specified by pl. Actions specified in phylink_connect_phy()
will be
performed.
Returns 0 on success or a negative errno.
-
int
phylink_fwnode_phy_connect
(struct phylink *pl, struct fwnode_handle *fwnode, u32 flags)¶ connect the PHY specified in the fwnode.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct fwnode_handle *fwnode
a pointer to a
struct fwnode_handle
.u32 flags
PHY-specific flags to communicate to the PHY device driver
Description
Connect the phy specified fwnode to the phylink instance specified by pl.
Returns 0 on success or a negative errno.
-
void
phylink_disconnect_phy
(struct phylink *pl)¶ disconnect any PHY attached to the phylink instance.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Disconnect any current PHY from the phylink instance described by pl.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
bool up
indicates whether the link is currently up.
Description
The MAC driver should call this driver when the state of its link changes (eg, link failure, new negotiation results, etc.)
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Start the phylink instance specified by pl, configuring the MAC for the
desired link mode(s) and negotiation style. This should be called from the
network device driver’s struct net_device_ops
ndo_open() method.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Stop the phylink instance specified by pl. This should be called from the
network device driver’s struct net_device_ops
ndo_stop() method. The
network device’s carrier state should not be changed prior to calling this
function.
This will synchronously bring down the link if the link is not already
down (in other words, it will trigger a mac_link_down()
method call.)
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
bool mac_wol
true if the MAC needs to receive packets for Wake-on-Lan
Description
Handle a network device suspend event. There are several cases: - If Wake-on-Lan is not active, we can bring down the link between
the MAC and PHY by calling
phylink_stop()
.
If Wake-on-Lan is active, and being handled only by the PHY, we can also bring down the link between the MAC and PHY.
If Wake-on-Lan is active, but being handled by the MAC, the MAC still needs to receive packets, so we can not bring the link down.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Undo the effects of phylink_suspend()
, returning the link to an
operational state.
-
void
phylink_ethtool_get_wol
(struct phylink *pl, struct ethtool_wolinfo *wol)¶ get the wake on lan parameters for the PHY
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_wolinfo *wol
a pointer to
struct ethtool_wolinfo
to hold the read parameters
Description
Read the wake on lan parameters from the PHY attached to the phylink instance specified by pl. If no PHY is currently attached, report no support for wake on lan.
-
int
phylink_ethtool_set_wol
(struct phylink *pl, struct ethtool_wolinfo *wol)¶ set wake on lan parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_wolinfo *wol
a pointer to
struct ethtool_wolinfo
for the desired parameters
Description
Set the wake on lan parameters for the PHY attached to the phylink
instance specified by pl. If no PHY is attached, returns EOPNOTSUPP
error.
Returns zero on success or negative errno code.
-
int
phylink_ethtool_ksettings_get
(struct phylink *pl, struct ethtool_link_ksettings *kset)¶ get the current link settings
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_link_ksettings *kset
a pointer to a
struct ethtool_link_ksettings
to hold link settings
Description
Read the current link settings for the phylink instance specified by pl. This will be the link settings read from the MAC, PHY or fixed link settings depending on the current negotiation mode.
-
int
phylink_ethtool_ksettings_set
(struct phylink *pl, const struct ethtool_link_ksettings *kset)¶ set the link settings
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
const struct ethtool_link_ksettings *kset
a pointer to a
struct ethtool_link_ksettings
for the desired modes
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
Restart negotiation for the phylink instance specified by pl. This will cause any attached phy to restart negotiation with the link partner, and if the MAC is in a BaseX mode, the MAC will also be requested to restart negotiation.
Returns zero on success, or negative error code.
-
void
phylink_ethtool_get_pauseparam
(struct phylink *pl, struct ethtool_pauseparam *pause)¶ get the current pause parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_pauseparam *pause
a pointer to a
struct ethtool_pauseparam
-
int
phylink_ethtool_set_pauseparam
(struct phylink *pl, struct ethtool_pauseparam *pause)¶ set the current pause parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_pauseparam *pause
a pointer to a
struct ethtool_pauseparam
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
.
Description
Read the Energy Efficient Ethernet error counter from the PHY associated with the phylink instance specified by pl.
Returns positive error counter value, or negative error code.
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
bool clk_stop_enable
allow PHY to stop receive clock
Description
Must be called either with RTNL held or within mac_link_up()
-
int
phylink_ethtool_get_eee
(struct phylink *pl, struct ethtool_eee *eee)¶ read the energy efficient ethernet parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_eee *eee
a pointer to a
struct ethtool_eee
for the read parameters
-
int
phylink_ethtool_set_eee
(struct phylink *pl, struct ethtool_eee *eee)¶ set the energy efficient ethernet parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ethtool_eee *eee
a pointer to a
struct ethtool_eee
for the desired parameters
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
struct ifreq *ifr
a pointer to a
struct ifreq
for socket ioctlsint cmd
ioctl cmd to execute
Description
Perform the specified MII ioctl on the PHY attached to the phylink instance specified by pl. If no PHY is attached, emulate the presence of the PHY.
SIOCGMIIPHY
:read register from the current PHY.
SIOCGMIIREG
:read register from the specified PHY.
SIOCSMIIREG
:set a register on the specified PHY.
Return
zero on success or negative error code.
-
int
phylink_speed_down
(struct phylink *pl, bool sync)¶ set the non-SFP PHY to lowest speed supported by both link partners
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
bool sync
perform action synchronously
Description
If we have a PHY that is not part of a SFP module, then set the speed
as described in the phy_speed_down()
function. Please see this function
for a description of the sync parameter.
Returns zero if there is no PHY, otherwise as per phy_speed_down()
.
-
int
phylink_speed_up
(struct phylink *pl)¶ restore the advertised speeds prior to the call to
phylink_speed_down()
Parameters
struct phylink *pl
a pointer to a
struct phylink
returned fromphylink_create()
Description
If we have a PHY that is not part of a SFP module, then restore the
PHY speeds as per phy_speed_up()
.
Returns zero if there is no PHY, otherwise as per phy_speed_up()
.
-
void
phylink_helper_basex_speed
(struct phylink_link_state *state)¶ 1000BaseX/2500BaseX helper
Parameters
struct phylink_link_state *state
a pointer to a
struct phylink_link_state
Description
Inspect the interface mode, advertising mask or forced speed and decide whether to run at 2.5Gbit or 1Gbit appropriately, switching the interface mode to suit. state->interface is appropriately updated, and the advertising mask has the “other” baseX_Full flag cleared.
-
void
phylink_decode_usxgmii_word
(struct phylink_link_state *state, uint16_t lpa)¶ decode the USXGMII word from a MAC PCS
Parameters
struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.uint16_t lpa
a 16 bit value which stores the USXGMII auto-negotiation word
Description
Helper for MAC PCS supporting the USXGMII protocol and the auto-negotiation code word. Decode the USXGMII code word and populate the corresponding fields (speed, duplex) into the phylink_link_state structure.
-
void
phylink_mii_c22_pcs_get_state
(struct mdio_device *pcs, struct phylink_link_state *state)¶ read the MAC PCS state
Parameters
struct mdio_device *pcs
a pointer to a
struct mdio_device
.struct phylink_link_state *state
a pointer to a
struct phylink_link_state
.
Description
Helper for MAC PCS supporting the 802.3 clause 22 register set for clause 37 negotiation and/or SGMII control.
Read the MAC PCS state from the MII device configured in config and
parse the Clause 37 or Cisco SGMII link partner negotiation word into
the phylink state structure. This is suitable to be directly plugged
into the mac_pcs_get_state()
member of the struct phylink_mac_ops
structure.
-
int
phylink_mii_c22_pcs_set_advertisement
(struct mdio_device *pcs, phy_interface_t interface, const unsigned long *advertising)¶ configure the clause 37 PCS advertisement
Parameters
struct mdio_device *pcs
a pointer to a
struct mdio_device
.phy_interface_t interface
the PHY interface mode being configured
const unsigned long *advertising
the ethtool advertisement mask
Description
Helper for MAC PCS supporting the 802.3 clause 22 register set for clause 37 negotiation and/or SGMII control.
Configure the clause 37 PCS advertisement as specified by state. This
does not trigger a renegotiation; phylink will do that via the
mac_an_restart()
method of the struct phylink_mac_ops
structure.
Returns negative error code on failure to configure the advertisement, zero if no change has been made, or one if the advertisement has changed.
-
int
phylink_mii_c22_pcs_config
(struct mdio_device *pcs, unsigned int mode, phy_interface_t interface, const unsigned long *advertising)¶ configure clause 22 PCS
Parameters
struct mdio_device *pcs
a pointer to a
struct mdio_device
.unsigned int mode
link autonegotiation mode
phy_interface_t interface
the PHY interface mode being configured
const unsigned long *advertising
the ethtool advertisement mask
Description
Configure a Clause 22 PCS PHY with the appropriate negotiation parameters for the mode, interface and advertising parameters. Returns negative error number on failure, zero if the advertisement has not changed, or positive if there is a change.
-
void
phylink_mii_c22_pcs_an_restart
(struct mdio_device *pcs)¶ restart 802.3z autonegotiation
Parameters
struct mdio_device *pcs
a pointer to a
struct mdio_device
.
Description
Helper for MAC PCS supporting the 802.3 clause 22 register set for clause 37 negotiation.
Restart the clause 37 negotiation with the link partner. This is
suitable to be directly plugged into the mac_pcs_get_state()
member
of the struct phylink_mac_ops
structure.
SFP support¶
-
struct
sfp_bus
¶ internal representation of a sfp bus
Definition
struct sfp_bus {
};
Members
-
struct
sfp_eeprom_id
¶ raw SFP module identification information
Definition
struct sfp_eeprom_id {
struct sfp_eeprom_base base;
struct sfp_eeprom_ext ext;
};
Members
base
base SFP module identification structure
ext
extended SFP module identification structure
Description
See the SFF-8472 specification and related documents for the definition of these structure members. This can be obtained from https://www.snia.org/technology-communities/sff/specifications
-
struct
sfp_upstream_ops
¶ upstream operations structure
Definition
struct sfp_upstream_ops {
void (*attach)(void *priv, struct sfp_bus *bus);
void (*detach)(void *priv, struct sfp_bus *bus);
int (*module_insert)(void *priv, const struct sfp_eeprom_id *id);
void (*module_remove)(void *priv);
int (*module_start)(void *priv);
void (*module_stop)(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);
};
Members
attach
called when the sfp socket driver is bound to the upstream (mandatory).
detach
called when the sfp socket driver is unbound from the upstream (mandatory).
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.
module_start
called after the PHY probe step
module_stop
called before the PHY is 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.
-
int
sfp_parse_port
(struct sfp_bus *bus, const struct sfp_eeprom_id *id, unsigned long *support)¶ Parse the EEPROM base ID, setting the port type
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp moduleconst struct sfp_eeprom_id *id
a pointer to the module’s
struct sfp_eeprom_id
unsigned long *support
optional pointer to an array of unsigned long for the ethtool support mask
Description
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
.
-
bool
sfp_may_have_phy
(struct sfp_bus *bus, const struct sfp_eeprom_id *id)¶ indicate whether the module may have a PHY
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp moduleconst struct sfp_eeprom_id *id
a pointer to the module’s
struct sfp_eeprom_id
Description
Parse the EEPROM identification given in id, and return whether this module may have a PHY.
-
void
sfp_parse_support
(struct sfp_bus *bus, const struct sfp_eeprom_id *id, unsigned long *support)¶ Parse the eeprom id for supported link modes
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp moduleconst struct sfp_eeprom_id *id
a pointer to the module’s
struct sfp_eeprom_id
unsigned long *support
pointer to an array of unsigned long for the ethtool support mask
Description
Parse the EEPROM identification information and derive the supported ethtool link modes for the module.
-
phy_interface_t
sfp_select_interface
(struct sfp_bus *bus, unsigned long *link_modes)¶ Select appropriate phy_interface_t mode
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp moduleunsigned long *link_modes
ethtool link modes mask
Description
Derive the phy_interface_t mode for the SFP module from the link modes mask.
-
void
sfp_bus_put
(struct sfp_bus *bus)¶ put a reference on the
struct sfp_bus
Parameters
struct sfp_bus *bus
the
struct sfp_bus
found viasfp_bus_find_fwnode()
Description
Put a reference on the struct sfp_bus
and free the underlying structure
if this was the last reference.
-
int
sfp_get_module_info
(struct sfp_bus *bus, struct ethtool_modinfo *modinfo)¶ Get the ethtool_modinfo for a SFP module
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp modulestruct ethtool_modinfo *modinfo
a
struct ethtool_modinfo
Description
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_eeprom
(struct sfp_bus *bus, struct ethtool_eeprom *ee, u8 *data)¶ Read the SFP module EEPROM
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp modulestruct ethtool_eeprom *ee
a
struct ethtool_eeprom
u8 *data
buffer to contain the EEPROM data (must be at least ee->len bytes)
Description
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_by_page
(struct sfp_bus *bus, const struct ethtool_module_eeprom *page, struct netlink_ext_ack *extack)¶ Read a page from the SFP module EEPROM
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp moduleconst struct ethtool_module_eeprom *page
a
struct ethtool_module_eeprom
struct netlink_ext_ack *extack
extack for reporting problems
Description
Read an EEPROM page as specified by the supplied page. See the
documentation for struct ethtool_module_eeprom
for the page to be read.
Returns 0 on success or a negative errno number. More error information might be provided via extack
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp module
Description
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.
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp module
Description
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.
-
struct sfp_bus *
sfp_bus_find_fwnode
(struct fwnode_handle *fwnode)¶ parse and locate the SFP bus from fwnode
Parameters
struct fwnode_handle *fwnode
firmware node for the parent device (MAC or PHY)
Description
Parse the parent device’s firmware node for a SFP bus, and locate
the sfp_bus structure, incrementing its reference count. This must
be put via sfp_bus_put()
when done.
Return
on success, a pointer to the sfp_bus structure,
NULL
if no SFP is specified,on failure, an error pointer value:
corresponding to the errors detailed for fwnode_property_get_reference_args().
-ENOMEM
if we failed to allocate the bus.an error from the upstream’s connect_phy() method.
-
int
sfp_bus_add_upstream
(struct sfp_bus *bus, void *upstream, const struct sfp_upstream_ops *ops)¶ parse and register the neighbouring device
Parameters
struct sfp_bus *bus
the
struct sfp_bus
found viasfp_bus_find_fwnode()
void *upstream
the upstream private data
const struct sfp_upstream_ops *ops
the upstream’s
struct sfp_upstream_ops
Description
Add upstream driver for the SFP bus, and if the bus is complete, register the SFP bus using sfp_register_upstream(). This takes a reference on the bus, so it is safe to put the bus after this call.
Return
on success, a pointer to the sfp_bus structure,
NULL
if no SFP is specified,on failure, an error pointer value:
corresponding to the errors detailed for fwnode_property_get_reference_args().
-ENOMEM
if we failed to allocate the bus.an error from the upstream’s connect_phy() method.
Parameters
struct sfp_bus *bus
a pointer to the
struct sfp_bus
structure for the sfp module
Description
Delete a previously registered upstream connection for the SFP
module. bus should have been added by sfp_bus_add_upstream()
.