linux/Documentation/vme_api.txt
<<
>>
Prefs
   1                        VME Device Driver API
   2                        =====================
   3
   4Driver registration
   5===================
   6
   7As with other subsystems within the Linux kernel, VME device drivers register
   8with the VME subsystem, typically called from the devices init routine.  This is
   9achieved via a call to the following function:
  10
  11        int vme_register_driver (struct vme_driver *driver);
  12
  13If driver registration is successful this function returns zero, if an error
  14occurred a negative error code will be returned.
  15
  16A pointer to a structure of type 'vme_driver' must be provided to the
  17registration function. The structure is as follows:
  18
  19        struct vme_driver {
  20                struct list_head node;
  21                const char *name;
  22                int (*match)(struct vme_dev *);
  23                int (*probe)(struct vme_dev *);
  24                int (*remove)(struct vme_dev *);
  25                void (*shutdown)(void);
  26                struct device_driver driver;
  27                struct list_head devices;
  28                unsigned int ndev;
  29        };
  30
  31At the minimum, the '.name', '.match' and '.probe' elements of this structure
  32should be correctly set. The '.name' element is a pointer to a string holding
  33the device driver's name.
  34
  35The '.match' function allows controlling the number of devices that need to
  36be registered. The match function should return 1 if a device should be
  37probed and 0 otherwise. This example match function (from vme_user.c) limits
  38the number of devices probed to one:
  39
  40        #define USER_BUS_MAX    1
  41        ...
  42        static int vme_user_match(struct vme_dev *vdev)
  43        {
  44                if (vdev->id.num >= USER_BUS_MAX)
  45                        return 0;
  46                return 1;
  47        }
  48
  49The '.probe' element should contain a pointer to the probe routine. The
  50probe routine is passed a 'struct vme_dev' pointer as an argument. The
  51'struct vme_dev' structure looks like the following:
  52
  53        struct vme_dev {
  54                int num;
  55                struct vme_bridge *bridge;
  56                struct device dev;
  57                struct list_head drv_list;
  58                struct list_head bridge_list;
  59        };
  60
  61Here, the 'num' field refers to the sequential device ID for this specific
  62driver. The bridge number (or bus number) can be accessed using
  63dev->bridge->num.
  64
  65A function is also provided to unregister the driver from the VME core and is
  66usually called from the device driver's exit routine:
  67
  68        void vme_unregister_driver (struct vme_driver *driver);
  69
  70
  71Resource management
  72===================
  73
  74Once a driver has registered with the VME core the provided match routine will
  75be called the number of times specified during the registration. If a match
  76succeeds, a non-zero value should be returned. A zero return value indicates
  77failure. For all successful matches, the probe routine of the corresponding
  78driver is called. The probe routine is passed a pointer to the devices
  79device structure. This pointer should be saved, it will be required for
  80requesting VME resources.
  81
  82The driver can request ownership of one or more master windows, slave windows
  83and/or dma channels. Rather than allowing the device driver to request a
  84specific window or DMA channel (which may be used by a different driver) this
  85driver allows a resource to be assigned based on the required attributes of the
  86driver in question:
  87
  88        struct vme_resource * vme_master_request(struct vme_dev *dev,
  89                u32 aspace, u32 cycle, u32 width);
  90
  91        struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace,
  92                u32 cycle);
  93
  94        struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route);
  95
  96For slave windows these attributes are split into the VME address spaces that
  97need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'.
  98Master windows add a further set of attributes in 'width' specifying the
  99required data transfer widths. These attributes are defined as bitmasks and as
 100such any combination of the attributes can be requested for a single window,
 101the core will assign a window that meets the requirements, returning a pointer
 102of type vme_resource that should be used to identify the allocated resource
 103when it is used. For DMA controllers, the request function requires the
 104potential direction of any transfers to be provided in the route attributes.
 105This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can
 106support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation.
 107If an unallocated window fitting the requirements can not be found a NULL
 108pointer will be returned.
 109
 110Functions are also provided to free window allocations once they are no longer
 111required. These functions should be passed the pointer to the resource provided
 112during resource allocation:
 113
 114        void vme_master_free(struct vme_resource *res);
 115
 116        void vme_slave_free(struct vme_resource *res);
 117
 118        void vme_dma_free(struct vme_resource *res);
 119
 120
 121Master windows
 122==============
 123
 124Master windows provide access from the local processor[s] out onto the VME bus.
 125The number of windows available and the available access modes is dependent on
 126the underlying chipset. A window must be configured before it can be used.
 127
 128
 129Master window configuration
 130---------------------------
 131
 132Once a master window has been assigned the following functions can be used to
 133configure it and retrieve the current settings:
 134
 135        int vme_master_set (struct vme_resource *res, int enabled,
 136                unsigned long long base, unsigned long long size, u32 aspace,
 137                u32 cycle, u32 width);
 138
 139        int vme_master_get (struct vme_resource *res, int *enabled,
 140                unsigned long long *base, unsigned long long *size, u32 *aspace,
 141                u32 *cycle, u32 *width);
 142
 143The address spaces, transfer widths and cycle types are the same as described
 144under resource management, however some of the options are mutually exclusive.
 145For example, only one address space may be specified.
 146
 147These functions return 0 on success or an error code should the call fail.
 148
 149
 150Master window access
 151--------------------
 152
 153The following functions can be used to read from and write to configured master
 154windows. These functions return the number of bytes copied:
 155
 156        ssize_t vme_master_read(struct vme_resource *res, void *buf,
 157                size_t count, loff_t offset);
 158
 159        ssize_t vme_master_write(struct vme_resource *res, void *buf,
 160                size_t count, loff_t offset);
 161
 162In addition to simple reads and writes, a function is provided to do a
 163read-modify-write transaction. This function returns the original value of the
 164VME bus location :
 165
 166        unsigned int vme_master_rmw (struct vme_resource *res,
 167                unsigned int mask, unsigned int compare, unsigned int swap,
 168                loff_t offset);
 169
 170This functions by reading the offset, applying the mask. If the bits selected in
 171the mask match with the values of the corresponding bits in the compare field,
 172the value of swap is written the specified offset.
 173
 174
 175Slave windows
 176=============
 177
 178Slave windows provide devices on the VME bus access into mapped portions of the
 179local memory. The number of windows available and the access modes that can be
 180used is dependent on the underlying chipset. A window must be configured before
 181it can be used.
 182
 183
 184Slave window configuration
 185--------------------------
 186
 187Once a slave window has been assigned the following functions can be used to
 188configure it and retrieve the current settings:
 189
 190        int vme_slave_set (struct vme_resource *res, int enabled,
 191                unsigned long long base, unsigned long long size,
 192                dma_addr_t mem, u32 aspace, u32 cycle);
 193
 194        int vme_slave_get (struct vme_resource *res, int *enabled,
 195                unsigned long long *base, unsigned long long *size,
 196                dma_addr_t *mem, u32 *aspace, u32 *cycle);
 197
 198The address spaces, transfer widths and cycle types are the same as described
 199under resource management, however some of the options are mutually exclusive.
 200For example, only one address space may be specified.
 201
 202These functions return 0 on success or an error code should the call fail.
 203
 204
 205Slave window buffer allocation
 206------------------------------
 207
 208Functions are provided to allow the user to allocate and free a contiguous
 209buffers which will be accessible by the VME bridge. These functions do not have
 210to be used, other methods can be used to allocate a buffer, though care must be
 211taken to ensure that they are contiguous and accessible by the VME bridge:
 212
 213        void * vme_alloc_consistent(struct vme_resource *res, size_t size,
 214                dma_addr_t *mem);
 215
 216        void vme_free_consistent(struct vme_resource *res, size_t size,
 217                void *virt,     dma_addr_t mem);
 218
 219
 220Slave window access
 221-------------------
 222
 223Slave windows map local memory onto the VME bus, the standard methods for
 224accessing memory should be used.
 225
 226
 227DMA channels
 228============
 229
 230The VME DMA transfer provides the ability to run link-list DMA transfers. The
 231API introduces the concept of DMA lists. Each DMA list is a link-list which can
 232be passed to a DMA controller. Multiple lists can be created, extended,
 233executed, reused and destroyed.
 234
 235
 236List Management
 237---------------
 238
 239The following functions are provided to create and destroy DMA lists. Execution
 240of a list will not automatically destroy the list, thus enabling a list to be
 241reused for repetitive tasks:
 242
 243        struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
 244
 245        int vme_dma_list_free(struct vme_dma_list *list);
 246
 247
 248List Population
 249---------------
 250
 251An item can be added to a list using the following function ( the source and
 252destination attributes need to be created before calling this function, this is
 253covered under "Transfer Attributes"):
 254
 255        int vme_dma_list_add(struct vme_dma_list *list,
 256                struct vme_dma_attr *src, struct vme_dma_attr *dest,
 257                size_t count);
 258
 259NOTE:   The detailed attributes of the transfers source and destination
 260        are not checked until an entry is added to a DMA list, the request
 261        for a DMA channel purely checks the directions in which the
 262        controller is expected to transfer data. As a result it is
 263        possible for this call to return an error, for example if the
 264        source or destination is in an unsupported VME address space.
 265
 266Transfer Attributes
 267-------------------
 268
 269The attributes for the source and destination are handled separately from adding
 270an item to a list. This is due to the diverse attributes required for each type
 271of source and destination. There are functions to create attributes for PCI, VME
 272and pattern sources and destinations (where appropriate):
 273
 274Pattern source:
 275
 276        struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);
 277
 278PCI source or destination:
 279
 280        struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
 281
 282VME source or destination:
 283
 284        struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
 285                u32 aspace, u32 cycle, u32 width);
 286
 286

 285                u32 A4ctions can be used to

 285  2*/a>3e_resource *res, int ena14" class="line" name="L114"> 114 159t#Lnsaction. Thi3"> 2373" c2c(cumeon/vme_api.tx6


 23tions can be used to
 199under resourc2 mana2ement, however some of the options are mutu2lly exclu2ive.
 257     236""> 248List Population
3me="L203"3 203
  40        #define USER_BUS_MAX me="L204"3 204
  40        #define USER_BUS_MAX m3="L204"3 ds, int ena14" class="l3ne" n3me="L206"> 206-------------------------3----
 274
 L232i114"rup0"3"> 1L274" class="line" name="L274"> 274
buffers which wi3l be 3ccessible by the VME bridge. These function3 do not h3ve
r">  40        #define USER_BUS_MAX  VME brid3e:
        void * v3e_all31e_api.tx6
                3ma_ad312        u32 A4ctions can bline" name="L212">t aL102"dased, otLntationid=" level02"d.tx6
 215X)


 237                voi3 *vir3,     href="Docue windowba  ons can b,ame="L211"> 26xt#L82" id=5" clar="Doc coretions can be used to
 257irqaces that
levelti57">X)
 235
31s selected in
)/aL220">priv 222
 248Liscumentati57">levelti57">X)
3224accessing memory 3hould322        ndowba  oourcmet="2" id="s u32 A4s. Cation/vme_a istent calritline" ndowba  .tx6
 232in2i114"rup0ine" exttions can be used to
 328levelti57">X)
priv 229
 130---------------------------
3 run link3list DMA transfers. The
3a hre3="DocuI114"rup0 Grned.
 130---------------------------
3 tion/vme31"> 231API introduce3 the 32f="Documentation/vmen/vmu32 cycle, u32 width);
3extended,3t otgivef=d="L274" class="line" name="L274"> 274 234
level02"daa hre)
 206-------------------------3 id="L2373 class="line" name="L2373> 23733" class="line" name="irqaurned.
,"> 248Liscumentati57">levelti57">X)
 238
 229
  40        #define USER_BUS_MAX e" name="3240"> 240of a list w3ll no33"Documentation/vmentat>  40        #define USER_BUS_MAX ng a list3to be
 222
 253covereda="L232"> enabled,
ame="L12
 130---------------------------
3*vme_new_3ma_list(struct vme_resou3ce *r3s);
 344
 345        int vme_dm3_list34e="L206"> 206-------------------------3>
 a b"L1k1"> "L12
 130---------------------------
3*" name="3L251" id="L251" class="l3ne" n3me="L2monitor"> 181<="Docu1me=m af14" cresource allocatiand pattetions can be used to
 152
 252destination at3ribut35ref="Documentation/vme_aon/vme_api.txt#lmaces that
 121Master window  id="L246" class="line" name="L246"> 246 206-------------------------3         3     struct vme_dma_attr3*src,3struct33 112d="L18n32 A4ctions can bene" name="L212"det="m" ia>
  40        #define USER_BUS_MAX d="L258" 3lass="line" name="L258">3258
 130---------------------------
3"L260"> 230        are not che3ked u35s selected in57"> 257lmame_ap> 121Master window  id="L246" class="line" name="L246"> 246 152
3="Documen3ation/vme_api.txt#L263" 3d="L233" claLtxt#L167Monitor Cname="L187"> 187Once a slave window has been 3ef="Docum3ntation/vme_api.txt#L2643 id="3264" co
 206-------------------------3266"> 2663/a>Transfer Attributes
<3 href3"Documname="Lbankss="ltxt#L167monitor">
 206-------------------------32tion/vme3api.txt#L268" id="L268" 3lass=3line" s="line" name="L2enabled,
ame="L12
 181be u1"> 261---------------
 257lmaseentation/vme_api.txt#L219" ipi.txt#L 270an item to3a lis3ts selected in

 277

 278PCI source o3 dest37a>---------------
 282VME source or destinati3n:
3i.txt#L283" id="L284" class="line"3name=381ass="line" name="L19lma>t aL1                dma_addr_t 1" /vme_api.txt#L286" id="L286" class=r w3me_dma_vm3_attribute(unsigned long3long 38rce *res, int *enable=" na(*ndowba  )(i1<)vme_api.txt#L199" id="L199" class="line3ame="L2853> 285               3u32 a3pace, u32 cycle, u32 width);
 286 238
 238
 285 130---------------------------
3_api.txe"3name=iS 286
1" vme_api.txt#L199" id="L199" class="line3ared for 3="cument3 co
3159t#Lnsa3tion. Thi3"> 2373" c2c(c3meon/3me_apiSlot Det=c87"> 187Once a slave window has been 3Docnsiste3t(struct v window must b3 conf39ref="Documentation/vme_api.txt#L125" id="L125" class="li3txt#L247"3ids, int ena14" class="l3ne3[t3ong *base, unsigned long long *size,
 261 211ase, unsigned long long *size,
 238
 199under resourc3 mana3ement,


footer"> Tne" name="L1LXR softws="locumenthref="Dochttp:// for211net/proj=c8s/lxr">LXR communityent,255" cl"> 2ritatiol ="L266" ocuhref="Docmailto:lxr@undux.no">lxr@undux.noent,.
subfooter"> lxr.undux.no kindly hosentatythref="Dochttp://www.ttepill-undpro.no">Rtepill Lndpro ASent,25ine" naass="LnduxL2enatioline"Manoped.