Documentation/driver-api/vme.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/vme.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/vme.rst
Extension
.rst
Size
10672 bytes
Lines
298
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

VME Device Drivers
==================

Driver registration
-------------------

As with other subsystems within the Linux kernel, VME device drivers register
with the VME subsystem, typically called from the devices init routine.  This is
achieved via a call to :c:func:`vme_register_driver`.

A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must
be provided to the registration function. Along with the maximum number of
devices your driver is able to support.

At the minimum, the '.name', '.match' and '.probe' elements of
:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name'
element is a pointer to a string holding the device driver's name.

The '.match' function allows control over which VME devices should be registered
with the driver. The match function should return 1 if a device should be
probed and 0 otherwise. This example match function (from vme_user.c) limits
the number of devices probed to one:

.. code-block:: c

	#define USER_BUS_MAX	1
	...
	static int vme_user_match(struct vme_dev *vdev)
	{
		if (vdev->id.num >= USER_BUS_MAX)
			return 0;
		return 1;
	}

The '.probe' element should contain a pointer to the probe routine. The
probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an
argument.

Here, the 'num' field refers to the sequential device ID for this specific
driver. The bridge number (or bus number) can be accessed using
dev->bridge->num.

A function is also provided to unregister the driver from the VME core called
:c:func:`vme_unregister_driver` and should usually be called from the device
driver's exit routine.


Resource management
-------------------

Once a driver has registered with the VME core the provided match routine will
be called the number of times specified during the registration. If a match
succeeds, a non-zero value should be returned. A zero return value indicates
failure. For all successful matches, the probe routine of the corresponding
driver is called. The probe routine is passed a pointer to the devices
device structure. This pointer should be saved, it will be required for
requesting VME resources.

The driver can request ownership of one or more master windows
(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`)
and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device
driver to request a specific window or DMA channel (which may be used by a
different driver) the API allows a resource to be assigned based on the required
attributes of the driver in question. For slave windows these attributes are
split into the VME address spaces that need to be accessed in 'aspace' and VME
bus cycle types required in 'cycle'. Master windows add a further set of
attributes in 'width' specifying the required data transfer widths. These
attributes are defined as bitmasks and as such any combination of the
attributes can be requested for a single window, the core will assign a window
that meets the requirements, returning a pointer of type vme_resource that

Annotation

Implementation Notes