xref: /illumos-gate/usr/src/man/man9e/mc_start.9e (revision 72d3dbb9ab4481606cb93caca98ba3b3a8eb6ce2)

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd May 31, 2016
.Dt MC_START 9E
.Os
.Sh NAME
.Nm mc_start ,
.Nm mc_stop
.Nd start and stop device entry points
.Sh SYNOPSIS
.In sys/mac_provider.h
.Ft int
.Fo prefix_m_start
.Fa "void *driver"
.Fc
.Ft void
.Fo prefix_m_stop
.Fa "void *driver"
.Fc
.Sh INTERFACE LEVEL
illumos DDI specific
.Sh PARAMETERS
.Bl -tag -width Ds
.It Fa driver
A pointer to the driver's private data that was passed in via the
.Sy m_pdata
member of the
.Xr mac_register 9S
structure to the
.Xr mac_register 9F
function.
.El
.Sh DESCRIPTION
The
.Fn mc_start
entry point for a driver indicates that it should initialize the chip
to be ready to send or receive data.
This entry point is guaranteed to be called before any entry points that are
expected to be able to send and receive data.
During this entry point, most devices will allocate DMA resources, enable the
link, and finish performing any necessary device programming.
.Pp
The
.Fn mc_stop
entry point for a driver indicates that it should tear down any
allocated resources for the driver and, after the function returns, it is
not expected to perform any additional I/O.
.Pp
The driver has access to its private data in the
.Fa driver
argument to either function, which it should cast to the
appropriate structure.
The system guarantees that only one of the
.Fn mc_start
and
.Fn mc_stop
functions will be called at any given time for a given instance.
Similarly, these should not be called at the same time as a device's
.Xr attach 9E
or
.Xr detach 9E
routine.
However, the driver may have other ongoing routines that it needs to protect
against.
The device driver should always apply the appropriate locking techniques needed
to ensure that access to the data in its soft state is protected.
.Sh RETURN VALUES
Upon successful completion, device drivers should return
.Sy 0
for the
.Fn mc_start
entry point.
Otherwise, they should return a non-zero positive error number to indicate the
error that occurred.
.Sh SEE ALSO
.Xr mac 9E ,
.Xr mac_register 9F ,
.Xr mac_register 9S