Move ifq_deq_{begin,commit,rollback} appart to keep man pages short,

readable and to emphasis that they are not the prefered API for your
drivers.

ok dlg@

3 files changed, 83 insertions, 46 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 555674da882..fd75d8a5256 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.259 2015/11/21 11:46:24 mpi Exp $
+#	$OpenBSD: Makefile,v 1.260 2015/11/23 10:45:26 mpi Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -17,8 +17,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	hardclock.9 hook_establish.9 hz.9 idgen32.9 \
 	ieee80211.9 ieee80211_crypto.9 ieee80211_input.9 ieee80211_ioctl.9 \
 	ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
-	ieee80211_radiotap.9 \
-	if_rxr_init.9 ifq_enqueue.9 iic.9 intro.9 inittodr.9 intr_barrier.9 \
+	ieee80211_radiotap.9 if_rxr_init.9 ifq_enqueue.9 ifq_deq_begin.9 \
+	iic.9 intro.9 inittodr.9 intr_barrier.9 \
 	kern.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \
 	loadfirmware.9 lock.9 log.9 \
 	malloc.9 membar_sync.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \
@@ -216,10 +216,9 @@ MLINKS+=ieee80211_proto.9 ieee80211_proto_attach.9 \
 MLINKS+=if_rxr_init.9 if_rxr_get.9 if_rxr_init.9 if_rxr_put.9 \
 	if_rxr_init.9 if_rxr_inuse.9 if_rxr_init.9 if_rxr_ioctl.9 \
 	if_rxr_init.9 if_rxr_info_ioctl.9
-MLINKS+=ifq_enqueue.9 ifq_dequeue.9 ifq_enqueue.9 ifq_deq_begin.9 \
-	ifq_enqueue.9 ifq_deq_commit.9 ifq_enqueue.9 ifq_deq_rollback.9 \
-	ifq_enqueue.9 ifq_purge.9 ifq_enqueue.9 ifq_len.9 \
-	ifq_enqueue.9 ifq_empty.9
+MLINKS+=ifq_enqueue.9 ifq_dequeue.9 ifq_enqueue.9 ifq_purge.9 \
+	ifq_enqueue.9 ifq_len.9 ifq_enqueue.9 ifq_empty.9
+MLINKS+=ifq_deq_begin.9 ifq_deq_commit.9 ifq_deq_begin.9 ifq_deq_rollback.9
 MLINKS+=iic.9 iic_acquire_bus.9 iic.9 iic_release_bus.9 iic.9 iic_exec.9 \
 	iic.9 iic_smbus_write_byte.9 iic.9 iic_smbus_read_byte.9 \
 	iic.9 iic_smbus_receive_byte.9
diff --git a/share/man/man9/ifq_deq_begin.9 b/share/man/man9/ifq_deq_begin.9
new file mode 100644
index 00000000000..02837dbb399
--- /dev/null
+++ b/share/man/man9/ifq_deq_begin.9
@@ -0,0 +1,74 @@
+.\"     $OpenBSD: ifq_deq_begin.9,v 1.1 2015/11/23 10:45:26 mpi Exp $
+.\"
+.\"  Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 23 2015 $
+.Dt IFQ_DEQ_BEGIN 9
+.Os
+.Sh NAME
+.Nm ifq_deq_begin ,
+.Nm ifq_deq_commit ,
+.Nm ifq_deq_rollback
+.Nd dequeue a mbuf from an interface sending queue
+.Sh SYNOPSIS
+.In net/if_var.h
+.Ft struft mbuf *
+.Fn ifq_deq_begin "struct ifqueue *ifq"
+.Ft void
+.Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m"
+.Ft void
+.Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m"
+.Sh DESCRIPTION
+The  
+.Fn ifq_deq_begin
+set of functions provides a non-atomic alternative to
+.Fn ifq_dequeue . 
+.Bl -tag -width Ds
+.It Fn ifq_deq_begin "struct ifqueue *ifq"
+Get a reference to the next mbuf to be transmitted from the
+.Fa ifq
+interface send queue.
+If an mbuf is to be transmitted, also acquire a lock on the send queue
+to exclude modification or freeing of the referenced mbuf.
+Its packet header must not be modified until the mbuf has been dequeued with
+.Fn ifq_deq_commit .
+.It Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m"
+Dequeue the mbuf
+.Fa m
+that was referenced by a previous call to
+.Fn ifq_deq_begin
+and release the lock on
+.Fa ifq .
+.It Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m"
+Release the lock on the interface send queue
+.Fa ifq
+that was acquired while a reference to
+.Fa m
+was being held.
+.El
+.Sh CONTEXT
+.Fn ifq_deq_begin ,
+.Fn ifq_deq_commit ,
+and
+.Fn ifq_deq_rollback
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn ifq_deq_begin
+return the next mbuf to be transmitted by the interface.
+If no packet is available for transmission,
+.Dv NULL
+is returned.
+.Sh SEE ALSO
+.Xr ifq_dequeue 9
diff --git a/share/man/man9/ifq_enqueue.9 b/share/man/man9/ifq_enqueue.9
index a53bde5e1f0..bd07658d563 100644
--- a/share/man/man9/ifq_enqueue.9
+++ b/share/man/man9/ifq_enqueue.9
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ifq_enqueue.9,v 1.1 2015/11/20 11:15:07 dlg Exp $
+.\"     $OpenBSD: ifq_enqueue.9,v 1.2 2015/11/23 10:45:26 mpi Exp $
 .\"
 .\"  Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
 .\"
@@ -14,15 +14,12 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 20 2015 $
+.Dd $Mdocdate: November 23 2015 $
 .Dt IFQ_ENQUEUE 9
 .Os
 .Sh NAME
 .Nm ifq_enqueue ,
 .Nm ifq_dequeue ,
-.Nm ifq_deq_begin ,
-.Nm ifq_deq_commit ,
-.Nm ifq_deq_rollback ,
 .Nm ifq_purge ,
 .Nm ifq_len ,
 .Nm ifq_empty
@@ -33,12 +30,6 @@
 .Fn ifq_enqueue "struct ifqueue *ifq" "struct mbuf *m"
 .Ft struft mbuf *
 .Fn ifq_dequeue "struct ifqueue *ifq"
-.Ft struft mbuf *
-.Fn ifq_deq_begin "struct ifqueue *ifq"
-.Ft void
-.Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m"
-.Ft void
-.Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m"
 .Ft unsigned int
 .Fn ifq_purge "struct ifqueue *ifq"
 .Ft unsigned int
@@ -63,29 +54,6 @@ and counted as a drop.
 Dequeue the next mbuf to be transmitted from the
 .Fa ifq
 interface send queue.
-.It Fn ifq_deq_begin "struct ifqueue *ifq"
-Get a reference to the next mbuf to be transmitted from the
-.Fa ifq
-interface send queue.
-If an mbuf is to be transmitted, also acquire a lock on the send queue
-to exclude modification or freeing of the referenced mbuf.
-The mbuf must not be freed, or have its length (m_pkthdr.len) or
-cookie (m_pkthdr.ph_cookie) modified until it has been dequeued
-completely with
-.Fn ifq_deq_commit .
-.It Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m"
-Dequeue the mbuf
-.Fa m
-that was referenced by a previous call to
-.Fn ifq_deq_begin
-and release the lock on
-.Fa ifq .
-.It Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m"
-Release the lock on the interface send queue
-.Fa ifq
-that was acquired while a reference to
-.Fa m
-was being held.
 .It Fn ifq_purge "struct ifqueue *ifq"
 Free all the mbufs on the interface send queue
 .Fa ifq .
@@ -108,9 +76,6 @@ is empty.
 .Sh CONTEXT
 .Fn ifq_enqueue ,
 .Fn ifq_dequeue ,
-.Fn ifq_deq_begin ,
-.Fn ifq_deq_commit ,
-.Fn ifq_deq_rollback ,
 .Fn ifq_purge ,
 .Fn ifq_len ,
 and
@@ -121,8 +86,6 @@ can be called during autoconf, from process context, or from interrupt context.
 returns 0 if the mbuf was successfully queued, or non-zero if mbuf was freed.
 .Pp
 .Fn ifq_dequeue
-and
-.Fn ifq_deq_begin
 return the next mbuf to be transmitted by the interface.
 If no packet is available for transmission,
 .Dv NULL
@@ -137,4 +100,5 @@ returns the number of mbufs on the queue.
 .Fn ifq_empty
 returns a non-zero value if the queue is empty, otherwise 0.
 .Sh SEE ALSO
+.Xr ifq_deq_begin 9 ,
 .Xr m_freem 9