# # ***************************************************************** # * * # * Copyright Compaq Computer Corporation, 2000 * # * * # * The software contained on this media is proprietary to * # * and embodies the confidential technology of Compaq * # * Computer Corporation. Possession, use, duplication or * # * dissemination of the software and media is authorized only * # * pursuant to a valid written license from Compaq Computer * # * Corporation. * # * * # * RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure * # * by the U.S. Government is subject to restrictions as set * # * forth in Subparagraph (c)(1)(ii) of DFARS 252.227-7013, * # * or in FAR 52.227-19, as applicable. * # * * # ***************************************************************** # # # HISTORY # # @(#)$RCSfile: README,v $ $Revision: 1.1.2.5 $ (DEC) $Date: 1997/04/16 15:35:59 $ # DEVICE DRIVER KIT FOR THE /dev/dmaex VME EXAMPLE DRIVER The dm100 directory contains the VME device driver kit for a fictitious /dev/dmaex device. The driver can be used to communicate with another system on the VMEbus or be modified to support a user installed VME device. The device driver can be statically or dynamically configured into the system without modifications to the device driver code. The driver was written to the Tru64 UNIX 4.0 single binary model. This driver was tested on Alpha AXPvme systems, Alpha VME 2100 systems, and Alpha VME 4/224, 4/288, 5/352, and 5/480 systems. The driver supports the following device driver routines: probe, cattach, ctlr_unattach, open, close, mmap, ioctl, read, write, minphys, strategy, and interrupt service routines. The driver's probe routine uses BADADDR to determine the presence of the VME device, initializes the device registers, checks for device errors, installs interrupt handlers for device interrupts, and creates events used for device interrupt signaling. The driver's strategy routine can be configured to perform data transfers using programmed I/O, using the VME adapter's block mode DMA engine, or using the VME device's DMA engine. The driver's ioctl commands are used to configure the transfer mode and to map or setup the appropriate VMEbus mapping for the transfer. Tru64 UNIX's read or write routines call down to the drivers read or write routines. The driver's read or write routines call the kernel physio routine specifying the minphys and strategy routines as parameters. The physio routine manages the transfer. It calls minphys to determine the maximum size of the transfer and then calls strategy to perform the transfer. If the requested transfer is larger then that specified by minphys, physio will segment the transfer. The driver's mmap routine can be configured to return the kernel page frame number (PFN) of a previously mapped VMEbus address, or the PFN of a physically contiguous write or read buffer. The physically contiguous buffers were allocated by the driver with the kernel's contig_malloc routine and the cma_dd subsystem. The mapped VMEbus address space was mapped by an ioctl command in the driver's ioctl routine. This routine supports Tru64 UNIX's mmap routine. It allows the user application program to have access to the VME device or kernel allocated physically contiguous memory. One of the driver's ioctl commands maps user memory to the VMEbus and wires the memory down. This memory can then be written or read by a VME device. Another ioctl command unwires the user memory and releases the DMA mapping resources. A driver's ioctl command allows an interrupt handler to be installed. The driver's interrupt service routine upon detection of an interrupt to the specified vector and VMEbus IRQ will issue a psignal to SIGUSR1. The user application needs to install a signal catcher for SIGUSR1 and wait for it to be signaled by the driver. Another ioctl command allows the interrupt handler to be removed. A driver's ioctl command allows the user application to post VMEbus interrupts at a specified interrupt request level and bus vector. The driver waits for the interrupt to be acknowledged or a timeout to occur. If a timeout occurs, the posted interrupt request will be cleared. Another ioctl command allows the application to clear a posted interrupt to a specific VMEbus interrupt request level and vector. A driver's ioctl command can be used to perform block DMA transfers using the VME adapters DMA engine. The ioctl commands are used to setup for the DMA transfer, perform the DMA and release the DMA resources. The DMA can be performed to user memory or kernel physically contiguous memory mmaped into user space. This allows the user application to DMA to or from the VMEbus using the ioctl commands. If the same VMEbus addresses are used for the DMA, the user application only needs to call the ioctl command to perform the DMA without freeing the DMA resources. A performance gain should be realized using the DMA engine in this manner. In addition to the driver and supporting files, this directory contains an example user program (dmaex_test.c) that demonstrates the driver's capabilities. The program includes tests for the following: o Exercise PCI byte/word(linear), sparse and dense mmap capabilities of the /dev/dmaex device driver. PCI byte/word linear mmap accesses are only supported on byte/word capable processors (ie. 5/352 and 5/480). o In lieu of using hardware assisted byte swap, the user program can perform software byte swap on the data transferred. o Transfer data using Tru64 UNIX's "read" and "write" driver routines. o transfer data using programmed I/O o transfer data using the VME adapter's hardware DMA engine to perform Master Block DMA transfers o transfer data using the VME device's hardware DMA engine o Map system memory onto the VMEbus and wait for a "psignal" from the /dev/dmaex driver on detection of a VMEbus interrupt. o Perform DMA reads and writes to user space buffers using the VME adapter's DMA engine and the /dev/dmaex driver's ioctl commands. The user buffers are wired down during the DMA transfer. o Perform DMA reads and writes to kernel physically contiguous buffers that are "mmaped" into user space. This test uses the VME adapter's DMA engine and the /dev/dmaex driver's ioctl commands and mmap routines. o Post an interrupt to the VMEbus and wait for the interrupt request to be acknowledged. o Clear a previously posted VME interrupt request The user should read the test program (dmaex_test.c) carefully before attempting to run it. The /usr/examples/ddk/src/dm100 directory contains the following files: File Contents ---- -------- README Instructions on how to get started DM100.list /dev/dmaex registration file dmaex.c /dev/dmaex device driver source code dmaexreg.h /dev/dmaex device register header file files /dev/dmaex files file fragment sysconfigtab /dev/dmaex configuration file dmaex_test.c /dev/dmaex test program source code ------------------------------------------------------------------ Perform the following tasks: 1. # csh 2. # cd /usr/sys/conf 3. If a /usr/sys/conf/BINARY.list file is not in this directory, create the BINARY.list. Edit the /usr/sys/conf/BINARY.list file and add the following line: /usr/examples/ddk/src/dm100: 4. Run the sourceconfig program # ./sourceconfig BINARY 5. # cd /usr/examples/ddk/src/dm100 6. The /usr/examples/ddk/src/dm100/dmaex.c device driver source code for the /dev/dmaex device has the Dmaex_No_Dev attribute set to 1 as a default. This default value allows the driver to be installed without the fictitious /dev/dmaex device hardware. It also allows the driver to be used for testing between two or more single-board-computers or for testing a VME device option. The dmaex_no_dev flag is used to skip over BADADDR, read_io_port, and write_io_port accesses to the fictitious 'dmaex' device hardware. The flag will be checked in dmaex_probe, dmaex_close, dmaex_strategy, and dmaex_intr1 driver routines. Before changing the default value of this attribute in /usr/examples/ddk/src/dm100/dmaex.c file or adding it to the sysconfigtab files file fragment for this device, examine the source code for possible side affects. 7. The /usr/examples/ddk/src/dm100/sysconfigtab files file fragment specifies a VBA_Option with a Csr1 VMEbus address of 0x800000. The dmaex.c fictitious device driver's dmaexdriver structure specifies an addr1_size of 8 and addr1_atype of VME_A24_UDATA_D32. This information instructs the the auto configuration software to map to the specified VMEbus address, for the number of bytes and with the specified address modifiers. The Csr1 address can not be within the configuration window setup for the VIP/VIC64 VME adapter. If this address is within the VIP/VIC64 window, change the value to be that of the VME device or another single-board-computer. The VBA_Option entry in the sysconfigtab files file fragment also specifies a Vector of 0xF0 with a VMEbus Bus_Priority of 1. The /dev/dmaex device driver uses these values to install interrupt service routines. This is done in the driver's probe routine. If multiple instances of the driver are to be installed, or the driver is to be installed on multiple single-board-computers within the VME backplane, then change these values to be unique for each instance of the driver. 8. Add the sysconfigtab file fragment to /etc/sysconfigtab # sysconfigdb -a -f /usr/examples/ddk/src/dm100/sysconfigtab dmaex 9. # cd /usr/sys/BINARY 10. Run the make program to generate the single binary module of the /dev/dmaex device driver in /usr/sys/BINARY directory. # make dmaex.mod 11. # cd /usr/examples/ddk/src/dm100 12. To make the executable test program # make dmaex_test 13. Go to step 14 to configure the device driver dynamically or step 20 to configure the driver into the kernel statically. 14. # cd /subsys 15. # ln -s /subsys/device.mth dmaex.mth 16. # ln -s /usr/sys/BINARY/dmaex.mod dmaex.mod 17. Run shutdown and reboot the system, the driver is ready to be dynamically loaded. However, the system needs to be rebooted to allow physically contiguous memory to be allocated for the driver. 18. Once the system has been rebooted, the driver can be loaded and unloaded with the following commands: # sysconfig -c dmaex # sysconfig -u dmaex 19. Refer to /usr/examples/ddk/src/dm100/dmaex_test.c for directions on running the test. This completes the dynamically loadable driver section. 20. # cd /usr/sys/conf 21. Copy the product registration file to /usr/sys/conf directory # cp /usr/examples/ddk/src/dm100/DM100.list DM100.list 22. Build a customized kernel with the dmaex driver statically installed. An example of building the customized kernel follows: # doconfig *** KERNEL CONFIGURATION AND BUILD PROCEDURE *** Enter a name for the kernel configuration file. [C177RG]: DM100 You want to name the configuration file 'DM100' Is that correct? (y/n) [y]: y *** KERNEL OPTION SELECTION *** . . . . Enter the selection number for each kernel option you want. For example, 1 3 [20]: 20 You do not want to select any kernel options. Is that correct? (y/n) [y]: y Do you want to edit the configuration file? (y/n) [n]: n *** PERFORMING KERNEL BUILD *** A log file listing special device files is located in /dev/MAKEDEV.log The new kernel is /sys/DM100/vmunix 23. The build is now done. Copy the customized kernel to the / root directory # cp /sys/DM100/vmunix /vmunix 24. Run shutdown and reboot the system with the new kernel, the driver is statically configured into the kernel. 25. Refer to /usr/examples/ddk/src/dm100/dmaex_test.c for directions on running the test. This completes the statically loadable driver section.