vme: Convert documentation to reStructuredText, move under driver APIs

+1

Documentation/driver-api/index.rst

··· 24 24 i2c 25 25 hsi 26 26 miscellaneous 27 + vme

+88 -27

Documentation/vme_api.txt Documentation/driver-api/vme.rst

··· 1 - VME Device Driver API 2 - ===================== 1 + VME Device Drivers 2 + ================== 3 3 4 4 Driver registration 5 - =================== 5 + ------------------- 6 6 7 7 As with other subsystems within the Linux kernel, VME device drivers register 8 8 with the VME subsystem, typically called from the devices init routine. This is 9 9 achieved via a call to the following function: 10 + 11 + .. code-block:: c 10 12 11 13 int vme_register_driver (struct vme_driver *driver, unsigned int ndevs); 12 14 ··· 18 16 A pointer to a structure of type 'vme_driver' must be provided to the 19 17 registration function. Along with ndevs, which is the number of devices your 20 18 driver is able to support. The structure is as follows: 19 + 20 + .. code-block:: c 21 21 22 22 struct vme_driver { 23 23 struct list_head node; ··· 42 38 probed and 0 otherwise. This example match function (from vme_user.c) limits 43 39 the number of devices probed to one: 44 40 41 + .. code-block:: c 42 + 45 43 #define USER_BUS_MAX 1 46 44 ... 47 45 static int vme_user_match(struct vme_dev *vdev) ··· 56 50 The '.probe' element should contain a pointer to the probe routine. The 57 51 probe routine is passed a 'struct vme_dev' pointer as an argument. The 58 52 'struct vme_dev' structure looks like the following: 53 + 54 + .. code-block:: c 59 55 60 56 struct vme_dev { 61 57 int num; ··· 74 66 A function is also provided to unregister the driver from the VME core and is 75 67 usually called from the device driver's exit routine: 76 68 69 + .. code-block:: c 70 + 77 71 void vme_unregister_driver (struct vme_driver *driver); 78 72 79 73 80 74 Resource management 81 - =================== 75 + ------------------- 82 76 83 77 Once a driver has registered with the VME core the provided match routine will 84 78 be called the number of times specified during the registration. If a match ··· 95 85 specific window or DMA channel (which may be used by a different driver) this 96 86 driver allows a resource to be assigned based on the required attributes of the 97 87 driver in question: 88 + 89 + .. code-block:: c 98 90 99 91 struct vme_resource * vme_master_request(struct vme_dev *dev, 100 92 u32 aspace, u32 cycle, u32 width); ··· 124 112 required. These functions should be passed the pointer to the resource provided 125 113 during resource allocation: 126 114 115 + .. code-block:: c 116 + 127 117 void vme_master_free(struct vme_resource *res); 128 118 129 119 void vme_slave_free(struct vme_resource *res); ··· 134 120 135 121 136 122 Master windows 137 - ============== 123 + -------------- 138 124 139 125 Master windows provide access from the local processor[s] out onto the VME bus. 140 126 The number of windows available and the available access modes is dependent on ··· 142 128 143 129 144 130 Master window configuration 145 - --------------------------- 131 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 146 132 147 133 Once a master window has been assigned the following functions can be used to 148 134 configure it and retrieve the current settings: 135 + 136 + .. code-block:: c 149 137 150 138 int vme_master_set (struct vme_resource *res, int enabled, 151 139 unsigned long long base, unsigned long long size, u32 aspace, ··· 165 149 166 150 167 151 Master window access 168 - -------------------- 152 + ~~~~~~~~~~~~~~~~~~~~ 169 153 170 154 The following functions can be used to read from and write to configured master 171 155 windows. These functions return the number of bytes copied: 156 + 157 + .. code-block:: c 172 158 173 159 ssize_t vme_master_read(struct vme_resource *res, void *buf, 174 160 size_t count, loff_t offset); ··· 181 163 In addition to simple reads and writes, a function is provided to do a 182 164 read-modify-write transaction. This function returns the original value of the 183 165 VME bus location : 166 + 167 + .. code-block:: c 184 168 185 169 unsigned int vme_master_rmw (struct vme_resource *res, 186 170 unsigned int mask, unsigned int compare, unsigned int swap, ··· 195 175 Parts of a VME window can be mapped into user space memory using the following 196 176 function: 197 177 178 + .. code-block:: c 179 + 198 180 int vme_master_mmap(struct vme_resource *resource, 199 181 struct vm_area_struct *vma) 200 182 201 183 202 184 Slave windows 203 - ============= 185 + ------------- 204 186 205 187 Slave windows provide devices on the VME bus access into mapped portions of the 206 188 local memory. The number of windows available and the access modes that can be ··· 211 189 212 190 213 191 Slave window configuration 214 - -------------------------- 192 + ~~~~~~~~~~~~~~~~~~~~~~~~~~ 215 193 216 194 Once a slave window has been assigned the following functions can be used to 217 195 configure it and retrieve the current settings: 196 + 197 + .. code-block:: c 218 198 219 199 int vme_slave_set (struct vme_resource *res, int enabled, 220 200 unsigned long long base, unsigned long long size, ··· 234 210 235 211 236 212 Slave window buffer allocation 237 - ------------------------------ 213 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 238 214 239 215 Functions are provided to allow the user to allocate and free a contiguous 240 216 buffers which will be accessible by the VME bridge. These functions do not have 241 217 to be used, other methods can be used to allocate a buffer, though care must be 242 218 taken to ensure that they are contiguous and accessible by the VME bridge: 219 + 220 + .. code-block:: c 243 221 244 222 void * vme_alloc_consistent(struct vme_resource *res, size_t size, 245 223 dma_addr_t *mem); ··· 251 225 252 226 253 227 Slave window access 254 - ------------------- 228 + ~~~~~~~~~~~~~~~~~~~ 255 229 256 230 Slave windows map local memory onto the VME bus, the standard methods for 257 231 accessing memory should be used. 258 232 259 233 260 234 DMA channels 261 - ============ 235 + ------------ 262 236 263 237 The VME DMA transfer provides the ability to run link-list DMA transfers. The 264 238 API introduces the concept of DMA lists. Each DMA list is a link-list which can ··· 267 241 268 242 269 243 List Management 270 - --------------- 244 + ~~~~~~~~~~~~~~~ 271 245 272 246 The following functions are provided to create and destroy DMA lists. Execution 273 247 of a list will not automatically destroy the list, thus enabling a list to be 274 248 reused for repetitive tasks: 249 + 250 + .. code-block:: c 275 251 276 252 struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); 277 253 ··· 281 253 282 254 283 255 List Population 284 - --------------- 256 + ~~~~~~~~~~~~~~~ 285 257 286 258 An item can be added to a list using the following function ( the source and 287 259 destination attributes need to be created before calling this function, this is 288 260 covered under "Transfer Attributes"): 289 261 262 + .. code-block:: c 263 + 290 264 int vme_dma_list_add(struct vme_dma_list *list, 291 265 struct vme_dma_attr *src, struct vme_dma_attr *dest, 292 266 size_t count); 293 267 294 - NOTE: The detailed attributes of the transfers source and destination 268 + .. note:: 269 + 270 + The detailed attributes of the transfers source and destination 295 271 are not checked until an entry is added to a DMA list, the request 296 272 for a DMA channel purely checks the directions in which the 297 273 controller is expected to transfer data. As a result it is ··· 303 271 source or destination is in an unsupported VME address space. 304 272 305 273 Transfer Attributes 306 - ------------------- 274 + ~~~~~~~~~~~~~~~~~~~ 307 275 308 276 The attributes for the source and destination are handled separately from adding 309 277 an item to a list. This is due to the diverse attributes required for each type ··· 312 280 313 281 Pattern source: 314 282 283 + .. code-block:: c 284 + 315 285 struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); 316 286 317 287 PCI source or destination: 318 288 289 + .. code-block:: c 290 + 319 291 struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); 320 292 321 293 VME source or destination: 294 + 295 + .. code-block:: c 322 296 323 297 struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, 324 298 u32 aspace, u32 cycle, u32 width); 325 299 326 300 The following function should be used to free an attribute: 327 301 302 + .. code-block:: c 303 + 328 304 void vme_dma_free_attribute(struct vme_dma_attr *attr); 329 305 330 306 331 307 List Execution 332 - -------------- 308 + ~~~~~~~~~~~~~~ 333 309 334 310 The following function queues a list for execution. The function will return 335 311 once the list has been executed: 312 + 313 + .. code-block:: c 336 314 337 315 int vme_dma_list_exec(struct vme_dma_list *list); 338 316 339 317 340 318 Interrupts 341 - ========== 319 + ---------- 342 320 343 321 The VME API provides functions to attach and detach callbacks to specific VME 344 322 level and status ID combinations and for the generation of VME interrupts with ··· 356 314 357 315 358 316 Attaching Interrupt Handlers 359 - ---------------------------- 317 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 360 318 361 319 The following functions can be used to attach and free a specific VME level and 362 320 status ID combination. Any given combination can only be assigned a single 363 321 callback function. A void pointer parameter is provided, the value of which is 364 322 passed to the callback function, the use of this pointer is user undefined: 323 + 324 + .. code-block:: c 365 325 366 326 int vme_irq_request(struct vme_dev *dev, int level, int statid, 367 327 void (*callback)(int, int, void *), void *priv); ··· 373 329 The callback parameters are as follows. Care must be taken in writing a callback 374 330 function, callback functions run in interrupt context: 375 331 332 + .. code-block:: c 333 + 376 334 void callback(int level, int statid, void *priv); 377 335 378 336 379 337 Interrupt Generation 380 - -------------------- 338 + ~~~~~~~~~~~~~~~~~~~~ 381 339 382 340 The following function can be used to generate a VME interrupt at a given VME 383 341 level and VME status ID: 342 + 343 + .. code-block:: c 384 344 385 345 int vme_irq_generate(struct vme_dev *dev, int level, int statid); 386 346 387 347 388 348 Location monitors 389 - ================= 349 + ----------------- 390 350 391 351 The VME API provides the following functionality to configure the location 392 352 monitor. 393 353 394 354 395 355 Location Monitor Management 396 - --------------------------- 356 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 397 357 398 358 The following functions are provided to request the use of a block of location 399 359 monitors and to free them after they are no longer required: 360 + 361 + .. code-block:: c 400 362 401 363 struct vme_resource * vme_lm_request(struct vme_dev *dev); 402 364 ··· 412 362 locations. The following function can be used to determine how many locations 413 363 are provided: 414 364 365 + .. code-block:: c 366 + 415 367 int vme_lm_count(struct vme_resource * res); 416 368 417 369 418 370 Location Monitor Configuration 419 - ------------------------------ 371 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 420 372 421 373 Once a bank of location monitors has been allocated, the following functions 422 374 are provided to configure the location and mode of the location monitor: 375 + 376 + .. code-block:: c 423 377 424 378 int vme_lm_set(struct vme_resource *res, unsigned long long base, 425 379 u32 aspace, u32 cycle); ··· 433 379 434 380 435 381 Location Monitor Use 436 - -------------------- 382 + ~~~~~~~~~~~~~~~~~~~~ 437 383 438 384 The following functions allow a callback to be attached and detached from each 439 385 location monitor location. Each location monitor can monitor a number of 440 386 adjacent locations: 387 + 388 + .. code-block:: c 441 389 442 390 int vme_lm_attach(struct vme_resource *res, int num, 443 391 void (*callback)(void *)); ··· 448 392 449 393 The callback function is declared as follows. 450 394 395 + .. code-block:: c 396 + 451 397 void callback(void *data); 452 398 453 399 454 400 Slot Detection 455 - ============== 401 + -------------- 456 402 457 403 This function returns the slot ID of the provided bridge. 404 + 405 + .. code-block:: c 458 406 459 407 int vme_slot_num(struct vme_dev *dev); 460 408 461 409 462 410 Bus Detection 463 - ============= 411 + ------------- 464 412 465 413 This function returns the bus ID of the provided bridge. 466 414 467 - int vme_bus_num(struct vme_dev *dev); 415 + .. code-block:: c 468 416 417 + int vme_bus_num(struct vme_dev *dev); 469 418

+1 -1

MAINTAINERS

··· 12877 12877 L: devel@driverdev.osuosl.org 12878 12878 S: Maintained 12879 12879 T: git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git 12880 - F: Documentation/vme_api.txt 12880 + F: Documentation/driver-api/vme.rst 12881 12881 F: drivers/staging/vme/ 12882 12882 F: drivers/vme/ 12883 12883 F: include/linux/vme*

Configure Feed

Configure Feed