.\"	$NetBSD: xbdback.4,v 1.5 2014/03/18 18:20:39 riastradh Exp $
.\"
.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jean-Yves Migeon <jym@NetBSD.org>.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd June 7, 2011
.Dt XBDBACK 4 xen
.Os
.Sh NAME
.Nm xbdback
.Nd Xen backend paravirtualized block device interface
.Sh SYNOPSIS
.Cd "pseudo-device xbdback"
.Sh DESCRIPTION
The
.Nm
interface forms the backend part of the paravirtualized drivers
used by
.Tn Xen
domains to offer a block device interface, similar to a hard disk.
.Nm
interfaces are backed either by a physical device directly,
or an image file mounted through
.Xr vnd 4 .
.Pp
All
.Nm
interfaces follow the
.Dq xbdbackXiY
naming convention, where
.Sq X
represents the guest domain identifier, and
.Sq Y
an arbitrary identifier.
This identifier is usually associated to the device node as seen
by the guest using
.Xr major 3
and
.Xr minor 3
numbers.
For example, identifier
.Do 769 Dc Po 0x301 Pc
means major
.Em 3
and minor
.Em 1 ,
identified as
.Dq hda1
under Linux convention.
For
.Nx ,
the guest device name specified in the guest configuration file
does not matter, and can be chosen arbitrarily.
.Pp
A
.Nm
interface will appear as a
.Xr xbd 4
block device inside a
.Nx
guest domain.
In the XenStore,
.Nm xbd
and
.Nm xbdback
are identified by
.Dq vbd
(virtual block device)
entries.
.Sh DIAGNOSTICS
.Bl -diag
.It "xbd backend: attach device %s (size %d) for domain %d"
Gives the device used as
.Nm
interface for the given guest domain, and its size, in bytes.
.It "xbd backend 0x%x for domain %d using event channel %d, protocol %s"
Gives the backend identifier, guest domain ID, event channel ID, and
protocol used for block level communication.
.It "xbdback %s: can't VOP_OPEN device 0x%x: %d"
When this message appears in the system message buffer with error 16
.Po Er EBUSY Pc ,
the device is likely to be already mounted.
It must be unmounted first, as the system will refuse to open
it a second time.
.El
.Sh SEE ALSO
.Xr vnd 4 ,
.Xr xbd 4 ,
.Xr xenbus 4
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 4.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Manuel Bouyer Aq Mt bouyer@NetBSD.org .