svn commit: r296072 - user/imp/camdoc

[Warner Losh]

Author: imp
Date: Thu Feb 25 23:00:07 2016
New Revision: 296072
URL: https://svnweb.freebsd.org/changeset/base/296072

Log:
  First cut at xpt_async and xpt_register_async man pages.

Deleted:
  user/imp/camdoc/xpt_async.9
Modified:
  user/imp/camdoc/Makefile
  user/imp/camdoc/cam_sim_alloc.9
  user/imp/camdoc/xpt_register_async.9

Modified: user/imp/camdoc/Makefile
==============================================================================
--- user/imp/camdoc/Makefile	Thu Feb 25 22:44:00 2016	(r296071)
+++ user/imp/camdoc/Makefile	Thu Feb 25 23:00:07 2016	(r296072)
@@ -402,6 +402,7 @@ MAN=	accept_filter.9 \
 	watchdog.9 \
 	xpt_print.9 \
 	xpt_print_path.9 \
+	xpt_register_async.9 \
 	xpt_release_ccb.9 \
 	zone.9
 
@@ -1908,6 +1909,7 @@ MLINKS+=vrele.9 vput.9 \
 	vrele.9 vunref.9
 MLINKS+=vslock.9 vsunlock.9
 MLINKS+=xpt_print_path.9 xpt_path_string.9
+MLINKS+=xpt_register_async.9 xpt_async.9
 MLINKS+=zone.9 uma.9 \
 	zone.9 uma_find_refcnt.9 \
 	zone.9 uma_zalloc.9 \

Modified: user/imp/camdoc/cam_sim_alloc.9
==============================================================================
--- user/imp/camdoc/cam_sim_alloc.9	Thu Feb 25 22:44:00 2016	(r296071)
+++ user/imp/camdoc/cam_sim_alloc.9	Thu Feb 25 23:00:07 2016	(r296072)
@@ -43,6 +43,16 @@
 .Ft struct cam_sim *
 .Fn cam_sim_alloc "sim_action_func sim_action" "sim_poll_func sim_poll" "const char * sim_name" "void *softc" "u_int32_t unit" "struct mtx *mtx" "int max_dev_transactions" "int max_tagged_dev_transactions" "struct cam_devq *queue"
 .Sh DESCRIPTION
+Create a CAM SIM.
+A SIM is a System Interface Module.
+It processes CCBs with its
+.Fn sim_action_func
+as described in
+.Xr cam.9 .
+.Pp
+The
+.Fn sim_poll_func
+is used to create crash dumps.
 .Sh SEE ALSO
 .Sh AUTHORS
 This manual page was written by

Modified: user/imp/camdoc/xpt_register_async.9
==============================================================================
--- user/imp/camdoc/xpt_register_async.9	Thu Feb 25 22:44:00 2016	(r296071)
+++ user/imp/camdoc/xpt_register_async.9	Thu Feb 25 23:00:07 2016	(r296072)
@@ -28,18 +28,106 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 19, 2016
+.Dd February 23, 2016
 .Dt XPT_REGISTER_ASYNC
 .Os
 .Sh NAME
 .Nm xpt_register_async
-.Nd xxx xxx xxx blah blah blah
+.Nd Manage async events
 .Sh SYNOPSIS
 .In cam/cam_xpt.h
+.Ft typedef void
+.Fn "\*(lp*cbfunc\*(rp" "void *cbarg" "u_int32_t code" "struct cam_path *path" "void *arg"
 .Ft cam_status
-.Fn xpt_async "int event" "ac_callback_t *cbfunc" "void *cbarg" "struct cam_path *path"
+.Fn xpt_register_async "int event" "ac_callback_t *cbfunc" "void *cbarg" "struct cam_path *path"
+.Ft void
+.Fn xpt_async "u_int32_t async_code" "struct cam_path *path" "void *async_arg"
 .Sh DESCRIPTION
+.Fn xpt_register_async 
+registers a callback to be called when an event happens.
+Callback numbers are bits, so the
+.Fn event
+parameter is an or'd together list of events that should be called.
+A mask of 0 will unregister the callback.
+Events on
+.Va path
+are delivered to this async function.
+When
+.Va path
+is
+.Va NULL
+the callback is registered for events on all paths and the
+callback function is expected to cope with unknown paths.
+.Va path
+may also have elements that are wildcards and so will be called for
+all paths that match.
+.Pp
+.Fn xpt_async
+queues the asynchronous event
+.Va code
+for the CAM
+.Va path
+specified.
+.Va async_arg
+contains additional information about the event.
+CAM knows about all the possible events, what is passed to them, and
+how large the argument is.
+CAM copies the event into the async CCB, so callers may modify the
+argument after
+.Fn xpt_async
+returns.
+.Pp
+When
+.Fn cbfunc
+is called, the
+.Va cbarg
+is the corresponding
+.Va cb
+from the
+.Fn xpt_register_async
+call.
+.Va code
+will contain the code from the
+.Fn xpt_async
+call.
+.Va path
+will be the specific path for the CAM object that the message was sent
+to.
+The
+.Va arg
+parameter is supplied by the caller of
+.Fn xpt_async
+and must match the following table.
+.Bl -tag -width indent
+.It Li AC_PATH_REGISTERED
+.Va struct ccb_pathinq
+.It Li AC_FOUND_DEVICE
+.Va struct ccb_getdev
+.It Li AC_TRANSFER_NEG
+.Va struct ccb_trans_settings
+.It Li AC_CONTRACT
+.Va struct ac_contract
+.It Li AC_UNIT_ATTENTION
+.Va struct ccb_scsiio
+.El
+The
+.Li AC_BUS_RESET ,
+.Li AC_UNSOL_RESEL ,
+.Li AC_SCSI_AEN ,
+.Li AC_SENT_BDR ,
+.Li AC_PATH_DEREGISTERED ,
+.Li AC_LOST_DEVICE ,
+.Li AC_INQ_CHANGED ,
+.Li AC_GETDEV_CHANGED ,
+and 
+.Li AC_ADVINFO_CHANGED
+messages send nothing.
+Messages not listed here also effectively send nothing, but should be
+added to either the table or the above list.
+The argument passed into .
 .Sh SEE ALSO
+.Xr cam 9 ,
+.Xr cam_ccb 9 ,
 .Xr cam_periph 9 ,
 .Xr xpt_release_ccb 9 ,
 .Xr xpt_setup_cbb 9