****************************************************************************

    FreeBSD KM alfa driver for PowerCrypt 7751-based board - release 1

****************************************************************************

About files in the package
==========================

This release consists of:

    an LKM driver that provides user mode interface to the 7751 services,

    header files that define user mode interfaces to the driver,

    a console test program that uses the header files and the driver.


Driver build and load procedures
--------------------------------

1. Files placement
------------------

If you have the source code
    Place Makefile into the                     /usr/src/lkm/pwrcrypt dir
    Place the driver source code tree into the  /usr/src/sys/pci/pwrcrypt dir
else
    Place pwrcrypt_mod.o into the               /usr/src/lkm/pwrcrypt dir


2. Driver building
------------------

If you have the source code
    Make the /usr/src/lkm/pwrcrypt dir current and enter 'make'.
    The driver object files *.o and the LKM 'pwrcrypt_mod.o' will be
    created in this dir.

3. Making devnode
-----------------

Enter 'mknod /dev/PwrCryptUMInterface 55 0'

'PwrCryptUMInterface' is the name of the device. It is defined in the
pwrcryptioctl.h file and is used by the driver clients to open the device.
If it's desirable to change it, the change must be synchronized with that
header file and client programs.

55 is the driver major number. It is hardcoded into the driver and can't
be changed without rebuilding.

0 is the device minor number. The driver doesn't check it and it generally
can be any number. The driver provides a single service point accessible
through the driver major number.


4. Driver loading
-----------------

Make the /usr/src/lkm/pwrcrypt dir current. It must already contain
pwrcrypt_mod.o.

Enter 'modload pwrcrypt_mod.o'. The driver's debug messages will appear on
the screen telling about the devices it has found.

Enter 'modstat' to list the loaded LKMs and see the PowerCrypt driver among
them.


5. Driver testing with testio.c
-------------------------------

Copy
    testio.c
    descomm.h
    pwrcryptioctl.h
    instrset.h
        to a directory.

Make that directory current and enter 'cc -D_BSD_DRIVER_BUILD_ testio.c'.
The file a.out will be created.
Run a.out.

testio.c opens the device, sends several ioctl requests and then exits.


6. Driver unloading
-------------------

Enter 'modstat' to list the loaded LKMs and see the module name for the
pwrcrypt LKM.

FreeBSD 2.2.6 that the driver is tested under is not capable to cleanly unload
an LKM-model driver for a PCI device. The effects of unloading such a driver
were not investigated and it is not recommended to unload it. If you, for some
reason, wish to try, enter 'modunload -n <module name>', then 'modstat' to see
that it has left the list.


Interfaces
----------

The headers pwrcryptioctl.h (includes instrset.h) define user-mode
IOCTL interface.

descomm.h - is not actually the part of interface, included for illustration
only and is used by the test program.


Test program files
------------------

testio.c opens the device, sends several ioctl requests and then exits.


Limitations
===========

This alpha driver is only able to detect the PowerCrypt hardware, make O/S
dependent work to acquire it and return success on IOCTLs send to it without
doing anything.
