usr/src/man/man9e/mc_start.9e

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd May 31, 2016
  15 .Dt MC_START 9E
  16 .Os
  17 .Sh NAME
  18 .Nm mc_start ,
  19 .Nm mc_stop
  20 .Nd start and stop device entry points
  21 .Sh SYNOPSIS
  22 .In sys/mac_provider.h
  23 .Ft int
  24 .Fo prefix_m_start
  25 .Fa "void *driver"
  26 .Fc
  27 .Ft void
  28 .Fo prefix_m_stop
  29 .Fa "void *driver"
  30 .Fc
  31 .Sh INTERFACE LEVEL
  32 illumos DDI specific
  33 .Sh PARAMETERS
  34 .Bl -tag -width Ds
  35 .It Fa driver
  36 A pointer to the driver's private data that was passed in via the
  37 .Sy m_pdata
  38 member of the
  39 .Xr mac_register 9S
  40 structure to the
  41 .Xr mac_register 9F
  42 function.
  43 .El
  44 .Sh DESCRIPTION
  45 The
  46 .Fn mc_start
  47 entry point for a driver indicates that it should initialize the chip
  48 to be ready to send or receive data.
  49 This entry point is guaranteed to be called before any entry points that are
  50 expected to be able to send and receive data.
  51 During this entry point, most devices will allocate DMA resources, enable the
  52 link, and finish performing any necessary device programming.
  53 .Pp
  54 The
  55 .Fn mc_stop
  56 entry point for a driver indicates that it should tear down any
  57 allocated resources for the driver and, after the function returns, it is
  58 not expected to perform any additional I/O.
  59 .Pp
  60 The driver has access to its private data in the
  61 .Fa driver
  62 argument to either function, which it should cast to the
  63 appropriate structure.
  64 The system guarantees that only one of the
  65 .Fn mc_start
  66 and
  67 .Fn mc_stop
  68 functions will be called at any given time for a given instance.
  69 Similarly, these should not be called at the same time as a device's
  70 .Xr attach 9E
  71 or
  72 .Xr detach 9E
  73 routine.
  74 However, the driver may have other ongoing routines that it needs to protect
  75 against.
  76 The device driver should always apply the appropriate locking techniques needed
  77 to ensure that access to the data in its soft state is protected.
  78 .Sh RETURN VALUES
  79 Upon successful completion, device drivers should return
  80 .Sy 0
  81 for the
  82 .Fn mc_start
  83 entry point.
  84 Otherwise, they should return a non-zero positive error number to indicate the
  85 error that occurred.
  86 .Sh SEE ALSO
  87 .Xr mac 9E ,
  88 .Xr mac_register 9F ,
  89 .Xr mac_register 9S