A VMEbus-Specific Reference Information

Previous versions of the operating system provided VMEbus device driver writers with numerous VMEbus-specific interfaces. To promote the portability of device drivers across different bus and CPU architectures, this version of Digital UNIX eliminates some of the VMEbus-specific interfaces and replaces them with more generic interfaces.

This appendix describes the following VMEbus-specific information:

Conventions for reference pages
Header file
Kernel interfaces
Data structures
Device driver interfaces

Refer to Writing Device Drivers: Reference for reference information on header files, kernel interfaces, ioctls, global variables, data structures, and driver interfaces that are not bus specific.

A.1 Conventions for Reference Pages

The following sections describe the conventions used for:

Header file
Kernel interfaces
Data structures
Device driver interfaces

int copyin (caddr_t user_src,
            caddr_t kernel_dest,
            u_int bcount)

The kernel interface function definition gives you the following information:

Return type
The data type of the return value, if the kernel interface returns data. If the kernel interface does not return a value, the void data type is used.
Kernel interface name
The kernel interface name, for example, copyin. Some kernel interfaces are in uppercase.
Argument names
The name of each kernel interface argument name. In the example, the argument names are user_src, kernel_dest, and bcount.
Argument types
The types for each of the arguments. In the example, these types are caddr_t and u_int.

This book uses the word kernel ``interface'' instead of kernel ``routine'' or kernel ``macro.''

Arguments

This section provides descriptions for the arguments associated with a given kernel interface. In most cases, argument descriptions begin with the word specifies to indicate that you pass the argument (with some specified value) to the kernel interface. If the type of the argument appears as a void *, the argument description states that you must define the type.

Description

This section contains explanations of the tasks performed by the kernel interface.

Notes

This section discusses information that falls into the following categories:

Hardware-specific information
Some kernel interfaces behave differently depending on the architecture of the hardware.
Operating system-specific information
Some kernel interfaces behave differently depending on the implementation of the operating system.
Information pertinent to device drivers
Some kernel interfaces require specific information important to the device driver writer.

Cautions

This section provides information of particular importance when you use the kernel interface. In many cases, the text in this section alerts you to anything that might cause a panic.

Errors

This section provides the possible error constants a given kernel interface can return, along with a short description of the error.

Side Effects

This section describes special processing performed by the kernel interface. For example, the Side Effects section for the uiomove kernel interface describes the members of the uio structure that it can update.

Return Values

This section describes the return values that a given kernel interface can return. In most cases, if the kernel interface returns an error value, this value is described in the Return Values section.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.1.3 Conventions for Data Structures

The descriptions of the data structures associated with VMEbus device drivers are presented in alphabetical order and in reference page style. The descriptions can include the following sections.

Name

This section lists the name of the structure along with a summary description of its purpose.

Include File

This section lists the header file, including the path, where the structure is defined.

Synopsis

This section considers the following when describing structures:

The C structure declaration is shown
This occurs when you need to understand or initialize all of the members of a structure.
The structure members are shown in a table
This occurs when you need to understand or reference some of the members of a particular structure.
No structure declaration or structure table is shown
This occurs when the structure is opaque. This means the members of the structure are manipulated by the Digital UNIX operating system. You do not manipulate or reference any of the members.

Members

This section provides a short description of each member of the structure.

Description

This section gives more details about the purpose of the structure.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.1.4 Conventions for Device Driver Interfaces

The descriptions of the device driver interfaces associated with VMEbus device drivers are presented in alphabetical order and in reference page style. The descriptions can include the following sections.

Name

This section lists the name of the driver interface along with a summary description of its purpose. In general, there is one interface described for each reference page. However, in some cases it makes sense to describe more than one interface on the same page if the interfaces are related. When this occurs, this section lists the names of all the interfaces it describes.

Entry Point

This section lists the structure or file where you specify the entry for the device driver interface.

Synopsis

This section shows the device driver interface function definition. The style used is that of the function definition, not the function call. This book assumes that you understand how to interpret the function definition and how to write an appropriate call for a specific interface. The presentation shown in the following example is of the function definition:

int xxprobe (io_handle_t addr1,
             struct controller *ctlr)

The previous interface function definition gives you the following information:

Return type
Gives the data type of the return value, if the interface returns data. If the interface does not return a value, the function definition shows a void data type.
Interface name
Gives the driver interface name. In the example, xxprobe is the name of the driver interface. The prefix xx indicates that this part of the name is variable. Replace it with the character prefix that represents the name of the device for which the driver is being written.
Argument names
Gives the name of each driver interface argument. In the example, the argument names are addr1 and ctlr.
Argument types
Gives the types for each of the arguments. If you must define the type of the argument, a void * is used. In the example, these types are io_handle_t and struct controller *. The term driver interface is used instead of driver routine to establish consistent terminology with that used for the kernel interfaces.

Arguments

This section provides descriptions for the arguments associated with a given driver interface. In most cases, argument descriptions begin with the word specifies to indicate that the driver writer passes the argument (with some specified value) to the driver interface.

Description

This section contains explanations of the tasks performed by the driver interface.

Notes

This section contains information about the driver interface pertinent to the device driver writer.

Return Values

This section describes the values that a given driver interface can return.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.2 Header File

Table A-1 lists the header file related to VMEbus device drivers and a short description of its contents. Device drivers should include header files that use the relative pathname instead of the explicit pathname. For example, although buf.h resides in /usr/sys/include/sys/buf.h, device drivers should include it as:

<sys/buf.h>

Table A-1: Summary Description of Header File Specific to VMEbus Device Drivers
Header File	Contents
`vbareg.h`	Contains definitions for VMEbus support.

NAME

vbareg.h - Contains definitions for VMEbus support

LOCATION

/usr/sys/include/io/dec/vme/vbareg.h

DESCRIPTION

The vbareg.h file defines bit constants that the dma_map_alloc, dma_map_load, vba_map_csr , vba_set_dma_addr, and busphys_to_iohandle kernel interfaces use. The file also defines bit constants that device drivers use for the addr1_atype and addr2_atype members of the driver structure.

WHEN TO INCLUDE

VMEbus block and character device drivers include this file in order to use the VMEbus bit constants.

OF SPECIAL INTEREST

Items of interest to device driver writers are the bit constants that the flags argument of dma_map_alloc, dma_map_load, vba_map_csr, vba_set_dma_addr, and busphys_to_iohandle use.

RELATED INFORMATION

Section A.4, Data Structures: driver

A.3 Kernel Interfaces

Table A-2 lists the kernel interfaces specific to VMEbus device drivers, along with short descriptions of their purpose.

Note
The following lists the header files that device drivers use most frequently:

#include <sys/types.h> #include <sys/errno.h> #include <io/common/devdriver.h> #include <sys/uio.h> #include <machine/cpu.h> #include <sys/conf.h> #include <sys/sysconfig.h>

Table A-2: Summary Description of Kernel Interfaces Specific to VMEbus Device Drivers
Kernel Interface	Summary Description
`vba_clear_irq`	Removes a posted interrupt request.
`vba_display_addr_type`	Prints the address type.
`vba_dma`	Performs Master Block Transfers with local DMA.
`vba_get_dma_addr`	Returns the VMEbus address and DMA flags.
`vba_get_vmeaddr`	Obtains a VMEbus address.
`vba_get_vmeaddr_am`	Obtains the VMEbus address modifiers.
`vba_map_csr`	Maps a VMEbus address CSR area.
`vba_post_irq`	Asserts an interrupt.
`vba_set_dma_addr`	Specifies a specific VMEbus address and DMA flags.
`vba_unmap_csr`	Unmaps a VMEbus address CSR area.

NAME

vba_clear_irq - Removes a posted interrupt request

SYNOPSIS

boolean_t vba_clear_irq (struct controller *ctlr,
                         unsigned int irq,
                         unsigned int status_ID)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
irq: Specifies the VMEbus interrupt request line on which you want to remove the previously posted interrupt.
status_ID: Specifies an ID that must match the status ID that you specified in the call to vba_post_irq. If the ID is zero (0) or the ID matches the currently posted status ID, vba_clear_irq removes the request at the specified interrupt request line.

DESCRIPTION

The vba_clear_irq interface removes an interrupt request that was posted on a previous call to vba_post_irq. If you pass a status_ID, it must match the value you passed to vba_post_irq. Otherwise, vba_clear_irq returns an error. If you pass the value zero (0) to status_ID, then vba_clear_irq removes any interrupt request on the specified interrupt request line.

RETURN VALUES

The vba_clear_irq interface returns one of the following values:

Value	Meaning
`TRUE`	The `vba_clear_irq` interface clears the posted interrupt on the specified interrupt request line. This VMEbus adapter provides no support for a `vba_clear_irq` interface.
`FALSE`	The `vba_clear_irq` interface failed to clear the posted interrupt on the specified interrupt request line. The status_ID you specified does not match the posted interrupt on the specified interrupt request line.

Value

Meaning

TRUE

The vba_clear_irq interface clears the posted interrupt on the specified interrupt request line.

This VMEbus adapter provides no support for a vba_clear_irq interface.

FALSE

The vba_clear_irq interface failed to clear the posted interrupt on the specified interrupt request line.

The status_ID you specified does not match the posted interrupt on the specified interrupt request line.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_post_irq

NAME

vba_display_addr_type - Prints the address type

SYNOPSIS

void vba_display_addr_type (vme_atype_t atype)

ARGUMENTS

atype: Specifies the address space and access mode of the control status register (CSR) area that you passed in a previous call to the vba_map_csr interface.

DESCRIPTION

The vba_display_addr_type interface prints on the console terminal the value of the address space and access mode of the CSR area during device autoconfiguration.

RETURN VALUES

None

RELATED INFORMATION

Section A.4, Data Structures: driver

NAME

vba_dma - Performs Master Block Transfers with local DMA

SYNOPSIS

#include <io/dec/vme/vbareg.h>

u_long vba_dma (struct controller *ctlr_p,
                dma_handle_t dma_handle)

ARGUMENTS

ctlr_p: Specifies a pointer to the controller structure associated with this controller. The interface uses this pointer to obtain bus-specific interfaces and data structures that it needs to perform the Master Block Transfer (MBLT) data transfer.
dma_handle: Specifies a handle to DMA resources associated with the mapping of an in-memory I/O buffer onto the VMEbus.

DESCRIPTION

If the VMEbus adapter provides a master block transfer local DMA engine, the vba_dma interface performs the transfer through DMA. If the hardware does not support a local DMA engine, vba_dma either performs the transfer through programmed I/O or returns an error indication.

The VME adapter support code may segment the transfer depending on the block-mode DMA hardware limitations. Further segmentation may occur depending on the amount of physically contiguous memory pages found in the virtual buffer supplied to dma_map_load.

NOTES

You must invoke the following interfaces with the appropriate specification of flags:

vba_set_dma_addr
Specify the VMEbus and DMA flags along with the VMEbus address. You must uniquely specify the flags DMA_IN (read from VMEbus to memory) or DMA_OUT (write from memory to VMEbus). These flag bits indicate to dma_map_alloc and dma_map_load that a local DMA engine will be utilized.
dma_map_alloc
Allocates resources for DMA data transfers
dma_map_load
Loads and sets allocated DMA resources and sets up a DMA data path for DMA data transfers
vba_dma
Performs the actual DMA or I/O copy transfer
dma_map_unload
Unloads the system DMA resources
dma_map_dealloc
Releases and deallocates the DMA resources previously allocated for DMA data transfers

EXAMPLE

See Section D.3 for a code example of the use of vba_dma.

RETURN VALUES

Upon successful completion, vba_dma returns the number of bytes transferred. This value should agree with the byte count value specified in the call to dma_map_load. If it does not, then an error occurred during the transfer.

If you specify DMA_SLEEP in the flags argument of either dma_map_alloc or dma_map_load, then vba_dma waits for the DMA resource if currently active. Access to the DMA hardware is single threaded at this point. If you do not specify DMA_SLEEP and vba_dma is active, a -1UL is returned to indicate that vba_dma is active. A -1UL is also returned if the VMEbus adapter does not supply support code for this function.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_set_dma_addr

Section A.4, Data Structures: controller

Writing Device Drivers: Reference: dma_map_alloc, dma_map_dealloc, dma_map_load, dma_map_unload

NAME

vba_get_dma_addr - Returns the VMEbus address and DMA flags

SYNOPSIS

void vba_get_dma_addr (struct controller *ctlr,
                       unsigned int param_flags,
                       unsigned int *flags,
                       vme_addr_t *vme_address)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
param_flags: Specifies the value passed to the flags argument in a call to dma_map_alloc or dma_map_load. You obtain this value in a previous call to the vba_set_dma_addr interface.
flags: Specifies a pointer to a buffer that stores the returned DMA flags.
vme_address: Specifies a pointer to a buffer that stores the returned VMEbus address.

DESCRIPTION

The vba_get_dma_addr interface returns the direct memory access (DMA) flags and VMEbus address specified in a previous call to vba_set_dma_addr. The interface recombines the VMEbus-related flags' bits with the DMA-related bits and stores them in the address passed to the flags argument.

NOTES

Bus adapter driver writers typically call vba_get_dma_addr to obtain the VMEbus address and DMA-related flags.

RETURN VALUES

The vba_get_dma_addr interface returns data explicitly to the pointers passed to the flags and vme_address arguments.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_set_dma_addr

NAME

vba_get_vmeaddr - Obtains a VMEbus address

SYNOPSIS

vme_addr_t vba_get_vmeaddr (struct controller *ctlr,
                            io_handle_t csr_addr_handle)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
csr_addr_handle: Specifies the I/O handle returned in a previous call to vba_map_csr. Note that the VMEbus configuration code calls the bus adapter-specific map_csr interface on the driver's behalf prior to calling the driver's probe interface. The bus configuration code converts the addresses specified for the Csr1 and Csr2 fields of the driver's VBA_Option entry in sysconfigtab, combined with information in driver structure members addr1_size, addr1_atype, addr2_size, and addr2_atype, into appropriate I/O handles.

DESCRIPTION

The vba_get_vmeaddr interface returns the VMEbus address associated with the specified I/O handle.

NOTES

The use of the io_handle_t data type for the address is new. Previous versions of this interface used a data type of u_long.

You can call the vba_get_vmeaddr_am interface to obtain the following information associated with the returned address: the VMEbus address space, access type, data transfer size, and swap mode.

RETURN VALUES

Upon successful completion, the vba_get_vmeaddr interface returns the vme_addr_t address corresponding to the I/O handle passed to the csr_addr_handle argument.

RELATED INFORMATION

Section A.5, Device Driver Interfaces: xxprobe

NAME

vba_get_vmeaddr_am - Obtains the VMEbus address modifiers

SYNOPSIS

vme_atype_t vba_get_vmeaddr_am (struct controller *ctlr,
                                io_handle_t csr_addr_handle)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
csr_addr_handle: Specifies the I/O handle returned in a previous call to vba_map_csr. Note that the VMEbus configuration code calls the bus adapter-specific map_csr interface on the driver's behalf prior to calling the driver's probe interface. The bus configuration code converts the addresses specified for the Csr1 and Csr2 fields of the driver's VBA_Option entry in sysconfigtab, combined with information in driver structure members addr1_size, addr1_atype, addr2_size, and addr2_atype, into appropriate I/O handles.

DESCRIPTION

The vba_get_vmeaddr_am interface obtains the VMEbus address modifiers for the VMEbus address associated with the I/O handle you pass to the csr_addr_handle argument. You obtained this handle in a previous call to vba_map_csr. These VMEbus address modifiers are associated with the valid bits passed to the atype argument of the vba_map_csr interface.

RETURN VALUES

Upon successful completion, vba_get_vmeaddr_am returns a value of type vme_atype_t. This return has the same definition as the atype argument in the vba_map_csr interface.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_map_csr

NAME

vba_map_csr - Maps a VMEbus address CSR area

SYNOPSIS

io_handle_t vba_map_csr (struct controller *ctlr,
                         vme_addr_t vme_address,
                         unsigned int bcnt,
                         vme_atype_t atype)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
vme_address: Specifies the VMEbus address to map for programmed I/O (PIO) access.
bcnt: Specifies the size (in bytes) of the device's CSR address region. Typically, the bus configuration code calls this interface on the driver's behalf prior to calling the driver's probe interface. The bus configuration code obtains the bcnt value, for example, for the first CSR address from the addr1_size member of the driver's driver structure.
atype: A bit encoded argument that specifies the address space, transfer size, access mode, and swap mode of the device's CSR area. A table of valid bits appears in the Description section.

DESCRIPTION

The vba_map_csr interface maps the specified VMEbus address space to an I/O handle (an io_handle_t data type). If you specify the VME_DENSE bit in the atype argument, vba_map_csr maps the CSR area such that there are no read-ahead side effects. This dense access maps large memory buffers (for example, graphics frame buffers) present in the A32 address space.

As the description for the atype argument stated, you can specify atype as the bitwise inclusive OR of the valid bits in the following table:

Bit Category	Value	Meaning
Swap mode bits	`VME_BS_NOSWAP`	Specifies no byte swapping.
	`VME_BS_BYTE`	Specifies byte swapping in bytes.
	`VME_BS_WORD`	Specifies byte swapping in words.
	`VME_BS_LWORD`	Specifies byte swapping in longwords.
	`VME_BS_QUAD`	Specifies byte swapping in quadwords.
Address space bits	`VME_A16`	Specifies a request for the 16-bit address space.
	`VME_A24`	Specifies a request for the 24-bit address space.
	`VME_A32`	Specifies a request for the 32-bit address space.
	`VME_A64`	Specifies a request for the 64-bit address space.
Transfer size bits	`VME_D08`	Specifies a request for the 8-bit data size.
	`VME_D16`	Specifies a request for the 16-bit data size.
	`VME_D32`	Specifies a request for the 32-bit data size.
Access mode bits	`VME_UDATA`	Specifies user data.
	`VME_UPROG`	Specifies a user program.
	`VME_SDATA`	Specifies supervisory data.
	`VME_SPROG`	Specifies a supervisory program.
CPU allocation space bits		Depending on VMEbus adapter implementation, this bit may not be applicable. To specify dense space on a platform for which the default CPU allocation space is sparse, you use the `VME_DENSE` bit.

EXAMPLE

The following code fragment shows how vba_map_csr references the values for the addr, size, and atype arguments during device autoconfiguration:


.
.
.

 struct controller *ctlr;
 struct driver *drp;

.
.
.

           ctlr->physaddr = ctlr->addr;
           ctlr->physaddr2 = ctlr->addr2;
           drp = ctlr->driver;

.
.
.

           /*
            * we need to connect the ctlr to the bus
            * before we map csr addresses because it will use
            * the map_csr routine found via the bus structure.
            */
            ctlr->bus_hd = bus;

           /* Map csr space(s)                     */
           /* Map csr1 address space if present    */
           if(drp->addr1_size) {
                   if ( (ctlr->addr = (caddr_t) vba_map_csr(ctlr,
                         (vme_addr_t)ctlr->physaddr, drp->addr1_size,
                         (vme_atype_t)drp->addr1_atype)) == 0){
                        printf("  %s%d not configured.\n",
                               ctlr->ctlr_name, ctlr->ctlr_num);
                        ctlr->addr = ctlr->physaddr;
                        continue;
                  }

.
.
.

RETURN VALUES

Upon successful completion, vba_map_csr returns an I/O handle that the driver can use as an argument to the interfaces called to read and write CSRs and copy buffers between system memory and I/O space. For example, you can pass this returned I/O handle in calls to read_io_port and write_io_port.

If unsuccessful, vba_map_csr returns an I/O handle of zero (0).

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_unmap_csr

Section A.4, Data Structures: driver

NAME

vba_post_irq - Asserts an interrupt

SYNOPSIS

unsigned int vba_post_irq (struct controller *ctlr,
                           unsigned int irq,
                           unsigned int status_ID,
                           int (*iack_isr) ())

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
irq: Specifies the VMEbus interrupt request line (1 through 7) on which you want to post the interrupt. At any point in time, there must be only one outstanding posted interrupt for each interrupt request line.
status_ID: Specifies the VMEbus vector to present on acknowledgement of an interrupt request.
iack_isr: Specifies the interrupt service interface to be called on successful presentation of the interrupt. The common interrupt service interface calls this interrupt handler on completion of the interrupt acknowledgement cycle.

DESCRIPTION

The vba_post_irq interface asserts an interrupt on the interrupt request line specified in irq. There is a maximum of one posted, unacknowledged interrupt per interrupt request line. If you attempt to post an interrupt on an interrupt request line on which there is a pending interrupt request, vba_post_irq returns an error.

When the interrupt is acknowledged and an interrupt callback service interface is provided through the iack_isr argument, the specified interrupt callback interface is invoked from the VMEbus adapter's common interrupt acknowledge handler. The user-specified interrupt callback interface is passed two arguments. The first argument is struct controller * ctlr, the controller structure pointer. The second argument is unsigned int irq, the interrupt request (IRQ) corresponding to the IRQ being acknowledged. The user-specified interrupt callback interface executes as an interrupt service interface with the same constraints on execution.

After the interrupt request has been acknowledged and the user-specified callback service interface (if provided) is invoked, the interrupt request line is made available for another call to the vba_post_irq interface.

RETURN VALUES

Upon successful completion, vba_post_irq returns the value 1. Otherwise, it returns the value zero (0). If the bus adapter is not capable of posting interrupts, vba_post_irq returns a -1.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_clear_irq

NAME

vba_set_dma_addr - Specifies a specific VMEbus address and DMA flags

SYNOPSIS

unsigned int vba_set_dma_addr (struct controller *ctlr,
                               vme_atype_t flags,
                               vme_addr_t vme_address)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
flags: Specifies special conditions that you want the system to perform. A table of valid bits appears in the Description section.
vme_address: Specifies the VMEbus address for the start of the address translation.

DESCRIPTION

The vba_set_dma_addr interface allows VMEbus device drivers to pass a specific VMEbus address and direct memory access (DMA) flags to the dma_map_alloc and dma_map_load interfaces.

The vba_set_dma_addr interface provides a mechanism to select the VME adapter's DMA engine to perform master block transfers. (See Section D.3 for a description and examples.) This is the recommended use of the vba_set_dma_addr interface. See the Notes section for a more detailed discussion on the use of vba_set_dma_addr.

The vba_set_dma_addr interface also provides a mechinism to map to a specific VMEbus address versus the dynamic allocation normally performed by dma_map_alloc or dma_map_load. The interface mimics the functionality that was available in the obsolete interfaces vballoc and vbasetup. Digital recommends that you not use the vba_set_dma_addr interface in this way unless you understand all of the issues related to the way the obsolete interfaces worked. See the Notes section for a discussion about the issues for this type of mapping.

The vba_set_dma_addr interface searches an internal data structure for a free resource and then does the following:

Marks the resource as being used
Fills in the DMA flags
Fills in the VMEbus address
Returns a special value to the caller

The caller passes this return value to the flags argument of dma_map_alloc or dma_map_load.

When the VME adapter's DMA allocation interface detects the special value, it calls vba_get_dma_addr to retrieve the DMA flags and VMEbus address.

As the description for the flags argument states, you can specify atype as the bitwise inclusive OR of the valid bits in the following table. The /usr/sys/include/io/dec/vme/vbareg.h file defines these and other bits.

Bit Category	Value	Meaning
Swap mode bits	`VME_BS_NOSWAP`	Specifies no byte swapping.
	`VME_BS_BYTE`	Specifies byte swapping in bytes.
	`VME_BS_WORD`	Specifies byte swapping in words.
	`VME_BS_LWORD`	Specifies byte swapping in longwords.
	`VME_BS_QUAD`	Specifies byte swapping in quadwords.
Address space bits	`VME_A16`	Specifies a request for the 16-bit address space.
	`VME_A24`	Specifies a request for the 24-bit address space.
	`VME_A32`	Specifies a request for the 32-bit address space.
	`VME_A64`	Specifies a request for the 64-bit address space.
Transfer size bits	`VME_D08`	Specifies a request for the 8-bit data size.
	`VME_D16`	Specifies a request for the 16-bit data size.
	`VME_D32`	Specifies a request for the 32-bit data size.
	`VME_D64`	Specifies a request for the 64-bit data size.
Access mode bits	`VME_UDATA`	Specifies user data.
	`VME_UPROG`	Specifies a user program.
	`VME_SDATA`	Specifies supervisory data.
	`VME_SPROG`	Specifies a supervisory program.
CPU allocation space bits		Depending on VMEbus adapter implementation, this bit may not be applicable. To specify dense space on a platform for which the default CPU allocation space is sparse, you use the `VME_DENSE` bit.

Note
The VME adapter's master block transfer DMA engine may not support all data transport sizes. See Section D.3 or the documentation that comes with your adapter for block mode restrictions.

You can pass the bitwise inclusive OR of the following special condition bits defined in /usr/sys/include/io/common/devdriver.h:

Value	Meaning
`DMA_GUARD_UPPER`	Allocates additional resources so that contiguous data overruns are captured by the system map error functions. This bit is probably most useful during device driver development and debugging.
`DMA_GUARD_LOWER`	Allocates additional resources so that contiguous data underruns are captured by the system map error functions. This bit is probably most useful during device driver development and debugging.
`DMA_SLEEP`	Puts the process to sleep if the system cannot allocate the necessary resources to perform a data transfer of size byte_count at the time the driver calls the interface.
`DMA_IN`	Selects the VME adapter's DMA engine to perform master block transfers to DMA data from the specified VMEbus address into system memory.
`DMA_OUT`	Selects the VME adapter's DMA engine to perform master block transfers to DMA data from the system memory to specified VMEbus address.
`DMA_ALL`	Returns a nonzero value, only if the system can satisfy a DMA transfer of size byte_count.

NOTES

To select the VMEbus adapter's master block transfer DMA engine for DMA transfer, specify either DMA_IN or DMA_OUT in the flags argument in the call to the vba_set_dma_addr interface. In addition, specify the bitwise inclusive OR of the VMEbus flag bits from the first table listed in the Description section. You also specify the starting VMEbus address of the transfer in the vme_address argument. You must then pass the return value from vba_set_dma_addr to either dma_map_alloc or dma_map_load. If you call both these interfaces, then you must pass the return value to both.

To perform the actual master block mode DMA transfer, call the vba_dma interface. When the transfer has completed, the VMEbus device driver can call vba_dma again to transfer the same buffer again. If the device driver needs to provide a different buffer, call dma_map_load and vba_dma to transfer the next buffer. This reloading of the buffer works providing the size of the buffer does not exceed the byte count passed to dma_map_alloc or to dma_map_load. When the master block transfer with local DMA engine is no longer needed, call dma_map_unload and dma_map_dealloc to return master block transfer DMA page map register resources back to the VMEbus adapter.

You can also use the vba_set_dma_addr interface to pass a specific VMEbus address to dma_map_alloc or dma_map_load. The purpose of doing this is to request the VMEbus adapter's allocation interface to map its system memory at a specific VMEbus address rather than the dynamic allocation that normally occurs when you call dma_map_alloc or dma_map_load. You must not specify the DMA_IN or DMA_OUT flags to the dma_map_alloc or dma_map_load interfaces to cause this desired mapping. You pass the return value from the vba_set_dma_addr interface to dma_map_alloc or dma_map_load . If the VMEbus adapter's allocation interface has not already allocated the VMEbus address space to another VMEbus device driver, and if there are enough page map registers available to handle the requested mapping size specified by the byte_count argument of dma_map_alloc or dma_map_load, the VMEbus adapter's DMA allocation interface will reserve the resources and return successfully. If you were to call dma_map_load, the system memory would be mapped to the VMEbus upon successful allocation. If the DMA resources were previously allocated, then dma_map_alloc or dma_map_load would return an error condition.

Upon successful completion of dma_map_load, the VMEbus device driver should call dma_get_curr_sgentry to obtain the actual address mapped to the VMEbus. The address returned by the call to dma_get_curr_sgentry may not be the specified address requested by vba_set_dma_addr. However, the address will be within the VMEbus window associated with the page map register representing the VMEbus address. The reason is that the VMEbus address consists of two parts. The first part is a VMEbus address that corresponds to a particular resource (page map register). This part of the address is a multiple of the bus window that the page map register represents (typically an alpha page size). The second part of the VMEbus address is the page offset of the system memory buffer from the start of an alpha page. You pass the system memory buffer to the virt_addr argument of the dma_map_load interface.

It is possible that the requested VMEbus address will not be mapped to memory or only partially mapped. This can occur in three cases:

If the page offset of the system memory buffer is greater then the page offset of the VMEbus address
If the page offset of the system memory buffer plus the byte count specified in dma_map_load is less than the page offset of the VMEbus address
If the page offset of the VMEbus address is greater then the page offset of the memory buffer but the requested byte count plus the specified VMEbus address exceeds the memory buffer

To guard against the previously described problems, ensure that the specified system memory buffer and VMEbus address are aligned to an alpha page boundary. The memory buffer allocated should be large enough to encompass the page offset of the required VMEbus address. You should pass the byte count of the memory buffer to the byte_count argument of the dma_map_alloc or dma_map_load interface. To get to the desired VMEbus address, add the correct page offset to the system memory buffer and to the VMEbus address returned in the call to dma_get_curr_sgentry.

RETURN VALUES

The vba_set_dma_addr can return one of the following values:

Value	Meaning
The value zero (0)	The system could not allocate internal resources.
A nonzero value	The system could allocate internal resources and fill in the internal data structure with DMA flags and the VMEbus address. Pass this return value to the flags argument of `dma_map_alloc` or `dma_map_load`.

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_dma, vba_get_dma_addr

Section D.3: Master Block Transfers with Local DMA

NAME

vba_unmap_csr - Unmaps a VMEbus address CSR area

SYNOPSIS

void vba_unmap_csr (struct controller *ctlr,
                    io_handle_t csr_addr_handle)

ARGUMENTS

ctlr: Specifies a pointer to a controller structure associated with this controller.
csr_addr_handle: Specifies the I/O handle that identifies the CSR area mapped in a previous call to vba_map_csr. Because you can multiply map VMEbus addresses, the specification of the VMEbus address and the atype is ambiguous. The context associated with each allocated I/O handle includes the atype and length of the allocation. The vba_map_csr interface saves this context and vba_unmap_csr deletes this context.

DESCRIPTION

The vba_unmap_csr interface unmaps the VMEbus address specified in the csr_addr_handle argument. This frees up the resources (for example, one or more outbound mapping registers) that were mapped in a previous call to vba_map_csr.

EXAMPLE

The following code fragment shows how vba_unmap_csr releases resources obtained in a previous call to vba_map_csr:


.
.
.

vba_unmap_csr(ctlr, (io_handle_t)ctlr->addr);

.
.
.

RETURN VALUES

None

RELATED INFORMATION

Section A.3, Kernel Interfaces: vba_map_csr

A.4 Data Structures

Table A-8 lists the data structures specific to VMEbus device drivers, along with short descriptions of their contents.

Table A-8: Summary Description of Data Structures Specific to VMEbus Device Drivers
Structure Name	Meaning
`controller`	Represents an instance of a controller entity.
`driver`	Defines driver entry points and other driver-specific information.
`vme_handler_info`	Contains interrupt handler information for device controllers connected to the VMEbus.

NAME

controller - Contains members that store information about hardware resources and store data for communication between the kernel and the device driver

INCLUDE FILE

/usr/sys/include/io/common/devdriver.h

SYNOPSIS

Member Name	Data Type
`bus_priority`	`int`
`ivnum`	`int`
`priority`	`int`

MEMBERS

bus_priority

DESCRIPTION

The controller structure represents an instance of a controller entity, one that connects logically to a bus. A controller can control devices that are directly connected or can perform some other controlling operation, such as a network interface or terminal controller operation.

RELATED INFORMATION

Section A.4, Data Structures: driver

Writing Device Drivers: Reference: controller

NAME

driver - Defines driver entry points and other driver-specific information

INCLUDE FILE

/usr/sys/include/io/common/devdriver.h

SYNOPSIS

Member Name	Data Type
`addr1_size`	`int`
`addr1_atype`	`int`
`addr2_size`	`int`
`addr2_atype`	`int`

MEMBERS

addr1_size

DESCRIPTION

The driver structure defines driver entry points and other driver-specific information. You declare and initialize an instance of this structure in the declarations section of the device driver. The bus configuration code uses the entry points defined in this structure during device autoconfiguration. The bus configuration code fills in the dev_list and ctlr_list arrays. The driver interfaces use these arrays (members of the device and controller structures) to get the structures for specific devices or controllers.

You can set the addr1_atype and addr2_atype members to the bitwise inclusive OR of the valid bits described in the following table:

Bit Category	Value	Meaning
Swap mode bits	`VME_BS_NOSWAP`	Specifies no byte swapping.
	`VME_BS_BYTE`	Specifies byte swapping in bytes.
	`VME_BS_WORD`	Specifies byte swapping in words.
	`VME_BS_LWORD`	Specifies byte swapping in longwords.
	`VME_BS_QUAD`	Specifies byte swapping in quadwords.
Address space bits	`VME_A16`	Specifies a request for the 16-bit address space.
	`VME_A24`	Specifies a request for the 24-bit address space.
	`VME_A32`	Specifies a request for the 32-bit address space.
	`VME_A64`	Specifies a request for the 64-bit address space.
Transfer size bits	`VME_D08`	Specifies a request for the 8-bit data size.
	`VME_D16`	Specifies a request for the 16-bit data size.
	`VME_D32`	Specifies a request for the 32-bit data size.
Access mode bits	`VME_UDATA`	Specifies user data.
	`VME_UPROG`	Specifies a user program.
	`VME_SDATA`	Specifies supervisory data.
	`VME_SPROG`	Specifies a supervisory program.
CPU allocation space bits		Depending on VMEbus adapter implementation, this bit may not be applicable. To specify dense space on a platform for which the default CPU allocation space is sparse, you use the `VME_DENSE` bit.

RELATED INFORMATION

Section A.4, Data Structures: controller

Writing Device Drivers: Reference: controller

NAME

vme_handler_info - Contains interrupt handler information for device controllers connected to the VMEbus

INCLUDE FILE

/usr/sys/include/io/dec/vme/vbareg.h

SYNOPSIS

Member Name	Data Type
`gen_intr_info`	`struct handler_intr_info`
`unsigned int`	`vec`
`irq`	`int`

MEMBERS

gen_intr_info

DESCRIPTION

The vme_handler_info structure contains interrupt handler information for device controllers connected to a VMEbus. This structure uses the generic handler_intr_info structure that contains all of the necessary information to add an interrupt handler for any bus. It also contains some VMEbus-specific members.

RELATED INFORMATION

Writing Device Drivers: Reference: handler_intr_info

A.5 Device Driver Interfaces

Table A-13 lists the device driver interfaces specific to VMEbus device drivers, along with short descriptions of their contents. See Writing Device Drivers: Reference for reference descriptions of the other driver interfaces.

Table A-13: Summary Description of Driver Interfaces Specific to VMEbus Device Drivers
Driver Interface	Summary Description
`xxprobe`	Determines whether the device exists.
`xxslave`	Checks that the device is valid for this controller.

NAME

xxprobe - Determines whether the device exists

ENTRY POINT

The driver structure

SYNOPSIS

int xxprobe (io_handle_t addr1,
             struct controller *ctlr)

ARGUMENTS

addr1

DESCRIPTION

A device driver's xxprobe interface performs tasks necessary to determine if the device exists and is functional on a given system. At boot time, the kernel performs checks to determine if the device is present before calling the xxprobe interface for statically configured drivers. For dynamically configured drivers, the xxprobe interface is called indirectly during the driver loading process.

The driver's configure interface calls the configure_driver interface to merge the driver's connectivity information into the system (hardware) configuration tree, which consists of bus, controller, and device structures. The call to configure_driver results in the system calling xxprobe for each instance of the controller present on the VMEbus.

Some tasks performed by the xxprobe interface vary, depending on whether the device driver is configured as static or loadable:

For static drivers
The xxprobe interface typically checks some device CSR to determine whether the physical device is present. If the device is not present, the device is not initialized and not available for use.
In previous versions of the operating system, you defined the device interrupt handlers for static device drivers in the system configuration file or a stanza.static file fragment. At system configuration time, the config program registered the defined device interrupt handlers. For this version of Digital UNIX, Digital requires that you register the device interrupt handlers for static device drivers in the same way that you register them for loadable device drivers: by calling the handler_add and handler_enable interfaces.
For loadable drivers
It is assumed that the device is physically present and addessable.

The xxprobe interface returns a nonzero value if the probe operation is successful. It returns the value zero (0) to indicate that the driver did not complete the probe operation.

The arguments you pass to the probe interface differ according to the bus on which the driver operates. The Synopsis section shows the arguments associated with a probe interface for a VMEbus.

NOTES

Device drivers pass the I/O handle to the following categories of interfaces, which are discussed in Writing Device Drivers: Tutorial. These interfaces can process the I/O handle to access the desired bus address space.

CSR I/O access interfaces
The CSR I/O access interfaces are read_io_port and write_io_port. These are generic interfaces that allow device drivers to read from and write to device registers. Using these interfaces to read data from and write data to a device register makes the device driver more portable across different bus architectures, different CPU architectures, and different CPU types within the same CPU architecture.
I/O copy interfaces
The I/O copy interfaces are io_copyin, io_copyio, io_copyout, and io_zero. These are generic interfaces that allow device drivers to perform I/O copy operations. Using these interfaces to perform the copy operation makes the device driver more portable across different CPU architectures and different CPU types within the same architecture.

RETURN VALUES

The xxprobe interface returns a nonzero value if the probe operation is successful. It returns the value zero (0) to indicate that the driver did not complete the probe operation.

RELATED INFORMATION

Section A.5, Device Driver Interfaces: xxslave

NAME

xxslave - Checks that the device is valid for this controller

ENTRY POINT

The driver structure

SYNOPSIS

int xxslave (struct device *device,
             io_handle_t addr1)

ARGUMENTS

device

Specifies a pointer to a device structure for this device. The VMEbus configuration code passes this pointer to the driver's xxslave interface. The interface can thus reference such information as the logical unit number of the device, whether the device is functional, and the controller number associated with the controller that this device is connected to.

addr1

Specifies an I/O handle that you can use to reference a device register located in the VMEbus address space. This I/O handle is created, passed, and can be used in the same manner as the addr1 I/O handle passed to xxprobe; see the reference page description of xxprobe.

In previous versions of the operating system, the xxslave interface for VMEbus device drivers specified a third argument called addr2. For this version of Digital UNIX, the VMEbus configuration code passes information to the addr2 member of the controller structure pointer instead of a third argument.

This member specifies an I/O handle that you can use to reference a device register located in the VMEbus onboard memory. This I/O handle is created, stored, and can be used in the same manner as the second I/O handle described for xxprobe; see the reference description of xxprobe.

DESCRIPTION

A device driver's xxslave interface is called only for a controller that has slave devices connected to it. This interface is called once for each slave attached to the controller.

The arguments you pass to the slave interface differ according to the bus on which the driver operates. The Synopsis section shows the arguments associated with a slave interface for a VMEbus.

RETURN VALUES

The xxslave interface returns a nonzero value if the device is present.

RELATED INFORMATION

Section A.5, Device Driver Interfaces: xxprobe

A VMEbus-Specific Reference Information

A.1 Conventions for Reference Pages

A.1.1 Conventions for Header File

Name

Location

Description

When to Include

Of Special Interest

Related Information

A.1.2 Conventions for Kernel Interfaces

Name

Synopsis

Arguments

Description

Notes

Cautions

Errors

Side Effects

Return Values

Related Information

A.1.3 Conventions for Data Structures

Name

Include File

Synopsis

Members

Description

Related Information

A.1.4 Conventions for Device Driver Interfaces

Name

Entry Point

Synopsis

Arguments

Description

Notes

Return Values

Related Information

A.2 Header File

NAME

LOCATION

DESCRIPTION

WHEN TO INCLUDE

OF SPECIAL INTEREST

RELATED INFORMATION

A.3 Kernel Interfaces

Note

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

RETURN VALUES

RELATED INFORMATION

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

RETURN VALUES

RELATED INFORMATION

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

NOTES

EXAMPLE

RETURN VALUES

RELATED INFORMATION

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

NOTES

RETURN VALUES

RELATED INFORMATION

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

NOTES

RETURN VALUES

RELATED INFORMATION

NAME