.Dd May 27, 2020
.Dt OPENCBM 4
.Os
.Sh NAME
.Nm opencbm
.Nd OpenCBM driver for parallel-port X[MA]-1541 cables
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
The
.Nm
driver supports Commodore disk drives connected to the parallel port using
an XM(P)-1541 or XA(P)-1541 cable.
.Ss Loader Tunables
The following loader tunables are used to set driver configuration at the
.Xr loader 8
prompt before booting the kernel, or they can be stored in
.Pa /boot/loader.conf
in order to automatically set them before booting the kernel.
It is also possible to use
.Xr kenv 1
to change these tunables before loading the
.Nm
driver.
.Bl -tag -width indent
.It Va cbm.cable
Set to 0 or 1 to explicitly select an XM-1541 (0) or XA-1541 (1) type cable.
The default value of -1 will attempt to auto-detect the cable type, which
only works reliably when
.Va cbm.reset
is active and the drive is connected and powered on while loading the
.Nm
driver.
.It Va cbm.hold_clk
Set to 0 explicitly to release the CLK line of the bus when idle.
The default (1) is to strictly follow C64 behavior, always holding the CLK
line.
.It Va cbm.reset
When set to 1 (default), execute a bus reset and wait for response from the
drive while loading the
.Nm
driver.
Set to 0 explicitly to load the driver without having to wait for the bus.
In this case, you should also select a cable type explicity.
.El
.Sh FILES
The
.Nm
driver creates the following device node:
.Bl -tag -width indent
.It Pa /dev/cbm
Device for communicating with a Commodore disk drive over a parallel-port
cable.
.El
.Sh EXAMPLES
To load the driver with a drive connected and powered on, auto-detecting
the cable type:
.Pp
.Dl kldload opencbm
.Pp
To load the driver without issuing a bus reset and selecting an active
(XA-1541) cable:
.Pp
.Dl kenv cbm.cable=1
.Dl kenv cbm.reset=0
.Dl kldload opencbm
.Pp
If you want to load the driver at system startup, adding it to
.Va kld_list
in
.Pa /etc/rc.conf
.Ns ,
it is recommended to disable
.Va cbm.reset
and explicitly select a cable type in
.Pa /boot/loader.conf
.Ns ,
e.g. add the following lines for a passive (XM-1541) cable:
.Pp
.Dl cbm.cable=0
.Dl cbm.reset=0
.Sh SEE ALSO
The cables supported by the
.Nm
driver (XM-1541, XA-1541 and their variations) are described on
.Lk https://sta.c64.org/xcables.html