diff options
Diffstat (limited to 'drivers/staging/vme/vme_api.txt')
-rw-r--r-- | drivers/staging/vme/vme_api.txt | 90 |
1 files changed, 52 insertions, 38 deletions
diff --git a/drivers/staging/vme/vme_api.txt b/drivers/staging/vme/vme_api.txt index 4910e92c52af..e8ff2151a487 100644 --- a/drivers/staging/vme/vme_api.txt +++ b/drivers/staging/vme/vme_api.txt @@ -18,37 +18,49 @@ registration function. The structure is as follows: struct vme_driver { struct list_head node; - char *name; - const struct vme_device_id *bind_table; - int (*probe) (struct device *, int, int); - int (*remove) (struct device *, int, int); - void (*shutdown) (void); - struct device_driver driver; + const char *name; + int (*match)(struct vme_dev *); + int (*probe)(struct vme_dev *); + int (*remove)(struct vme_dev *); + void (*shutdown)(void); + struct device_driver driver; + struct list_head devices; + unsigned int ndev; }; -At the minimum, the '.name', '.probe' and '.bind_table' elements of this -structure should be correctly set. The '.name' element is a pointer to a string -holding the device driver's name. The '.probe' element should contain a pointer -to the probe routine. - -The arguments of the probe routine are as follows: - - probe(struct device *dev, int bus, int slot); - -The '.bind_table' is a pointer to an array of type 'vme_device_id': - - struct vme_device_id { - int bus; - int slot; +At the minimum, the '.name', '.match' and '.probe' elements of this structure +should be correctly set. The '.name' element is a pointer to a string holding +the device driver's name. + +The '.match' function allows controlling the number of devices that need to +be registered. 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: + + #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 'struct vme_dev' pointer as an argument. The +'struct vme_dev' structure looks like the following: + + struct vme_dev { + int num; + struct vme_bridge *bridge; + struct device dev; + struct list_head drv_list; + struct list_head bridge_list; }; -Each structure in this array should provide a bus and slot number where the core -should probe, using the driver's probe routine, for a device on the specified -VME bus. - -The VME subsystem supports a single VME driver per 'slot'. There are considered -to be 32 slots per bus, one for each slot-ID as defined in the ANSI/VITA 1-1994 -specification and are analogious to the physical slots on the VME backplane. +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 and is usually called from the device driver's exit routine: @@ -59,9 +71,11 @@ usually called from the device driver's exit routine: Resource management =================== -Once a driver has registered with the VME core the provided probe routine will -be called for each of the bus/slot combination that becomes valid as VME buses -are themselves registered. The probe routine is passed a pointer to the devices +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. @@ -71,13 +85,13 @@ specific window or DMA channel (which may be used by a different driver) this driver allows a resource to be assigned based on the required attributes of the driver in question: - struct vme_resource * vme_master_request(struct device *dev, + struct vme_resource * vme_master_request(struct vme_dev *dev, vme_address_t aspace, vme_cycle_t cycle, vme_width_t width); - struct vme_resource * vme_slave_request(struct device *dev, + struct vme_resource * vme_slave_request(struct vme_dev *dev, vme_address_t aspace, vme_cycle_t cycle); - struct vme_resource *vme_dma_request(struct device *dev, + struct vme_resource *vme_dma_request(struct vme_dev *dev, vme_dma_route_t route); For slave windows these attributes are split into those of type 'vme_address_t' @@ -301,10 +315,10 @@ status ID combination. Any given combination can only be assigned a single callback function. A void pointer parameter is provided, the value of which is passed to the callback function, the use of this pointer is user undefined: - int vme_irq_request(struct device *dev, int level, int statid, + int vme_irq_request(struct vme_dev *dev, int level, int statid, void (*callback)(int, int, void *), void *priv); - void vme_irq_free(struct device *dev, int level, int statid); + void vme_irq_free(struct vme_dev *dev, int level, int statid); The callback parameters are as follows. Care must be taken in writing a callback function, callback functions run in interrupt context: @@ -318,7 +332,7 @@ Interrupt Generation The following function can be used to generate a VME interrupt at a given VME level and VME status ID: - int vme_irq_generate(struct device *dev, int level, int statid); + int vme_irq_generate(struct vme_dev *dev, int level, int statid); Location monitors @@ -334,7 +348,7 @@ Location Monitor Management The following functions are provided to request the use of a block of location monitors and to free them after they are no longer required: - struct vme_resource * vme_lm_request(struct device *dev); + struct vme_resource * vme_lm_request(struct vme_dev *dev); void vme_lm_free(struct vme_resource * res); @@ -380,4 +394,4 @@ Slot Detection This function returns the slot ID of the provided bridge. - int vme_slot_get(struct device *dev); + int vme_slot_get(struct vme_dev *dev); |