Sophie: opencbm-0.4.2a-5mdv2010.0 i586

opencbm-0.4.2a-5mdv2010.0.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
 <TITLE>OpenCBM 0.4.2 Users Guide: Installation: Installing OpenCBM on Linux (cbm4linux)</TITLE>
 <LINK HREF="opencbm-10.html" REL=next>
 <LINK HREF="opencbm-8.html" REL=previous>
 <LINK HREF="opencbm.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="opencbm-10.html">Next</A>
<A HREF="opencbm-8.html">Previous</A>
<A HREF="opencbm.html#toc4">Contents</A>
<HR>
<H2><A NAME="cbm4linux-install"></A> 4.1 <A HREF="opencbm.html#toc4.1">Installing OpenCBM on Linux (cbm4linux)</A></H2>

<P>The kernel module (cbm.o) does not require any kernel patches and should
compile right out of the box, at least with kernel 2.2.x, 2.4.x and 2.6.x, but 2.0.x
might still work as well.</P>
<P>If you intend to modify the drive routines for `d64copy' and `cbmformat' you
also need a crossassembler. `LINUX/config.make' comes with rules for A.Fachat's
`xa' (available from 
<A HREF="http://www.floodgap.com/retrotech/xa/">http://www.floodgap.com/retrotech/xa/</A> or 
<A HREF="http://www.lb.shuttle.de/puffin/cbm4linux/">http://www.lb.shuttle.de/puffin/cbm4linux/</A>; Note: xa has not been tested
lately, and might not work anymore) and Ullrich von Bassewitz' `cl65' (comes
with cc65, 
<A HREF="http://www.cc65.org/">http://www.cc65.org/</A>).
Starting with version cbm4linux 0.2.3, OpenCBM includes precompiled 6502
binaries, so as long as you don't touch the .a65 files, there's no need for a
crossassembler.</P>
<P>This package comes with a .spec file for those who want to build binary .RPMs.
See the RPM documentation (outside of this paper) for details about the build
process. Additionally, all files needed to built Debian .DEB packages are
included. If you upgrade from a previous (non-RPM and non-DEB) version and want
to install a packetized binary version (RPM or DEB), don't forget to remove the
old files hanging aroung (just do "<I>make uninstall</I>", preferably in the
*old* source directory. For a >= 0.4.0 version of OpenCBM, change the line to
"<I>make -f LINUX/Makefile uninstall</I>".).</P>

<H3>Compile-time configuration</H3>

<P>The compile-time configuration is located in `LINUX/config.make'. Check the
KERN_FLAGS line if you're running kernel 2.0.x or if you don't want to use the
Linux parport subsystem for some reason. Same goes for SMP machines.</P>


<H3>Compilation</H3>

<P>Type</P>
<P>
<UL>
<LI><I>make -f LINUX/Makefile</I>    (no root privileges required)

to  build  the  kernel module, libraries and utility programs (no
root privileges required),
</LI>
<LI><I>make -f LINUX/Makefile dev</I>    (as root; only needed if you do not use UDEV (
<A HREF="http://en.wikipedia.org/wiki/Udev">http://en.wikipedia.org/wiki/Udev</A>)

to   create   the  character  device "/dev/cbm" with major 10 and
minor 177 (this number is registered,  so  it  shouldn't  collide
with anything else :)). Finally
</LI>
<LI><I>make -f LINUX/Makefile install</I>     (as root)

will  install  all  necessary  stuff  to  /usr/local/...  (can be
changed in `LINUX/config.make')</LI>
</UL>
</P>

<H3>Loading the module</H3>

<P>If  you're  using  the  parport subsystem (which is default), you
should now be able to load the driver module by issuing (as root)</P>

<P>
<UL>
<LI><I>/sbin/depmod</I></LI>
<LI><I>/sbin/modprobe parport</I>      (unless parport is compiled into the kernel, or already loaded)</LI>
<LI><I>/sbin/modprobe cbm lp=</I>your_lp   (usually 0, which is default); if you only have one parallel port, you can also use <I>/sbin/modprobe cbm</I> instead)</LI>
</UL>
</P>

<P>or, when built with -DDIRECT_PORT_ACCESS:</P>

<P>
<UL>
<LI><I>/sbin/modprobe cbm port=your_ioport irq=your_irq</I>
(default is 0x378 for port, 7 for irq)</LI>
</UL>
</P>
<P>Check <CODE>/var/log/messages</CODE> if the correct cable type was recognized
(XA1541/XM1541).</P>


<H3>Troubleshooting</H3>

<P>Finding the cause of a failure condition can be hard. Anyway, the
following tips might help you:</P>
<P>
<UL>
<LI>Check <CODE>/var/log/messages</CODE>; it might give you some hints.
</LI>
<LI>If you are using the parport subsystem (no -DDIRECT_PORT_ACCESS):

<UL>
<LI>the port might be occupied by another device (e.g. `lp.o')
cbm.o does NOT support port sharing (wouldn't work anyway).
Enter <I>cat /proc/parport/port/devices</I> to find out.
</LI>
<LI>parport_pc might not use an IRQ.
<I>/etc/modules.conf</I> should contain something like:
<BLOCKQUOTE><CODE>
<PRE>
       alias parport_lowlevel parport_pc
       options parport_pc io=0x378 irq=7
     
</PRE>
</CODE></BLOCKQUOTE>

Check the interrupts with <I>cat /proc/interrupts</I>.</LI>
</UL>

</LI>
<LI>Using direct port access (with -DDIRECT_PORT_ACCESS):

<UL>
<LI>The port/IRQ might occupied by another driver (e.g. parport.o)
Enter <I>cat /proc/interrupts</I> and <I>cat /proc/ioports</I> to find
out.</LI>
</UL>
</LI>
</UL>
</P>


<H3>Device access</H3>

<P>As a first test, try something simple like</P>
<P>
<UL>
<LI><I>cbmctrl command 8 I0:</I>    (assuming drive 8)</LI>
<LI><I>cbmctrl status 8</I></LI>
</UL>
</P>

<P>(no root privileges required)</P>

<P>Failure can be caused by:
<UL>
<LI>Possibly, the shared library in <CODE>/usr/local/lib/</CODE> cannot be found;
in this case, add <CODE>/usr/local/lib/</CODE> to <CODE>/etc/ld.so.conf</CODE> and
execute <I>ldconfig</I> (as root)</LI>
<LI>You might not have the necessary rights to the <CODE>/dev/cbm</CODE> device;
try <I>chmod 777 /dev/cbm</I></LI>
<LI>incorrect module parameters</LI>
<LI>wrong BIOS settings (esp. IRQ)</LI>
<LI>broken cable</LI>
</UL>
</P>

<H3>Runtime configuration</H3>

<P>Most probably, you will want to add this to <CODE>/etc/modules.conf</CODE> to have
the driver loaded on demand: (the file is called <CODE>/etc/conf.modules</CODE> on
some older SuSE systems)</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    alias char-major-10-177 cbm
    options cbm [options]
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>With [options] being one or more of:</P>
<P>
<UL>
<LI><I>lp=*lp*</I>       (parport only, as used in <I>/sbin/modprobe</I> above)</LI>
<LI><I>irq=*irq*</I>     (direct port only, as used in <I>/sbin/modprobe</I> above)</LI>
<LI><I>port=*port*</I>   (direct port only, as used in <I>/sbin/modprobe</I> above)</LI>
<LI><I>cable=*n*</I>      force cable type:
<UL>
<LI>               -1  for autodetection (default)</LI>
<LI>                0  for XM1541 (non-inverting)</LI>
<LI>                1  for XA1541 (inverting)</LI>
</UL>
</LI>
<LI><I>reset=*n*</I>     initializing behaviour:
<UL>
<LI>               -1  smart IEC reset (direct port default);
only change the status of the reset line if it was set on start</LI>
<LI>                0  no IEC reset on driver start</LI>
<LI>                1  force IEC reset (parport default);
always reset the device on driver start</LI>
</UL>
</LI>
</UL>
</P>

<H3>Security considerations</H3>

<P>By default, OpenCBM installs the device driver so that anyone has access to
the CBM devices:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    $ ls -l /dev/cbm
    crw-rw-rw- 1 root root 10, 177 2007-11-11 14:34 /dev/cbm
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>You might want to change this behaviour to control more specifically who is
allowed to use OpenCBM, and who is not.</P>
<P>The best way is to define a group (for example, `cbmuser') and restrict the
access rights to the owner (root) and this group (cbmuser) only.</P>
<P>I assume you already have defined a group `cbmuser', for example, by using
groupadd(8) (all Linux variants) or addgroup(8) (all Debian based Linux
distributions).</P>
<P>Now, you can restrict the access by two different means, depending upon if you
are using devfs or udev:
<UL>
<LI>If you are using devfs (all Linux kernels prior to
2.6.0), this can be done by issuing the commands

<BLOCKQUOTE><CODE>
<PRE>
    $ chmod 660 /dev/cbm
    $ chgrp cbmuser /dev/cbm
    $ ls -l /dev/cbm
    crw-rw---- 1 root cbmuser 10, 177 2007-11-11 14:34 /dev/cbm
 
</PRE>
</CODE></BLOCKQUOTE>
</LI>
<LI>If you are using udev (newer 2.6.x kernels) instead, you have to modify
the file /etc/udev/rules.d/45-opencbm-parallel.rules. It looks like follows:
<BLOCKQUOTE><CODE>
<PRE>
ACTION!="add", GOTO="opencbm_plugin_xa1541_rules_end"

# xa1541/xm1541 parallel port driver
KERNEL=="cbm", GROUP="root", MODE="0666"

LABEL="opencbm_plugin_xa1541_rules_end"
 
</PRE>
</CODE></BLOCKQUOTE>


To change the group to another one, change the part `root' in `GROUP="root"' 
by the name of the group you want to use. To change the access mode,
change `MODE="0666"' to `MODE="0660"', so your files looks like:
<BLOCKQUOTE><CODE>
<PRE>
ACTION!="add", GOTO="opencbm_plugin_xa1541_rules_end"

# xa1541/xm1541 parallel port driver
KERNEL=="cbm", GROUP="cbmuser", MODE="0660"

LABEL="opencbm_plugin_xa1541_rules_end"
 
</PRE>
</CODE></BLOCKQUOTE>


For your changes to take effect, issue
<BLOCKQUOTE><CODE>
<PRE>
 $ rmmod cbm
 $ modprobe cbm
 
</PRE>
</CODE></BLOCKQUOTE>

You might also want to adjust the file `sys/linux/45-opencbm-parallel.rules', which
is used when installing the OpenCBM driver out of the source package.</LI>
</UL>
</P>

<P>Congratulation, you have successfully set up your OpenCBM installation!</P>


<HR>
<A HREF="opencbm-10.html">Next</A>
<A HREF="opencbm-8.html">Previous</A>
<A HREF="opencbm.html#toc4">Contents</A>
</BODY>
</HTML>