1 /* 2 * dspdefs.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Bridge driver entry point and interface function declarations. 7 * 8 * Notes: 9 * The DSP API obtains it's function interface to 10 * the Bridge driver via a call to bridge_drv_entry(). 11 * 12 * Bridge services exported to Bridge drivers are initialized by the 13 * DSP API on behalf of the Bridge driver. 14 * 15 * Bridge function DBC Requires and Ensures are also made by the DSP API on 16 * behalf of the Bridge driver, to simplify the Bridge driver code. 17 * 18 * Copyright (C) 2005-2006 Texas Instruments, Inc. 19 * 20 * This package is free software; you can redistribute it and/or modify 21 * it under the terms of the GNU General Public License version 2 as 22 * published by the Free Software Foundation. 23 * 24 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 25 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 26 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 27 */ 28 29 #ifndef DSPDEFS_ 30 #define DSPDEFS_ 31 32 #include <dspbridge/brddefs.h> 33 #include <dspbridge/cfgdefs.h> 34 #include <dspbridge/chnlpriv.h> 35 #include <dspbridge/dspdeh.h> 36 #include <dspbridge/devdefs.h> 37 #include <dspbridge/io.h> 38 #include <dspbridge/msgdefs.h> 39 40 /* Handle to Bridge driver's private device context. */ 41 struct bridge_dev_context; 42 43 /*--------------------------------------------------------------------------- */ 44 /* BRIDGE DRIVER FUNCTION TYPES */ 45 /*--------------------------------------------------------------------------- */ 46 47 /* 48 * ======== bridge_brd_monitor ======== 49 * Purpose: 50 * Bring the board to the BRD_IDLE (monitor) state. 51 * Parameters: 52 * dev_ctxt: Handle to Bridge driver defined device context. 53 * Returns: 54 * 0: Success. 55 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 56 * -EPERM: Other, unspecified error. 57 * Requires: 58 * dev_ctxt != NULL 59 * Ensures: 60 * 0: Board is in BRD_IDLE state; 61 * else: Board state is indeterminate. 62 */ 63 typedef int(*fxn_brd_monitor) (struct bridge_dev_context *dev_ctxt); 64 65 /* 66 * ======== fxn_brd_setstate ======== 67 * Purpose: 68 * Sets the Bridge driver state 69 * Parameters: 70 * dev_ctxt: Handle to Bridge driver defined device info. 71 * brd_state: Board state 72 * Returns: 73 * 0: Success. 74 * -EPERM: Other, unspecified error. 75 * Requires: 76 * dev_ctxt != NULL; 77 * brd_state <= BRD_LASTSTATE. 78 * Ensures: 79 * brd_state <= BRD_LASTSTATE. 80 * Update the Board state to the specified state. 81 */ 82 typedef int(*fxn_brd_setstate) (struct bridge_dev_context 83 * dev_ctxt, u32 brd_state); 84 85 /* 86 * ======== bridge_brd_start ======== 87 * Purpose: 88 * Bring board to the BRD_RUNNING (start) state. 89 * Parameters: 90 * dev_ctxt: Handle to Bridge driver defined device context. 91 * dsp_addr: DSP address at which to start execution. 92 * Returns: 93 * 0: Success. 94 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 95 * -EPERM: Other, unspecified error. 96 * Requires: 97 * dev_ctxt != NULL 98 * Board is in monitor (BRD_IDLE) state. 99 * Ensures: 100 * 0: Board is in BRD_RUNNING state. 101 * Interrupts to the PC are enabled. 102 * else: Board state is indeterminate. 103 */ 104 typedef int(*fxn_brd_start) (struct bridge_dev_context 105 * dev_ctxt, u32 dsp_addr); 106 107 /* 108 * ======== bridge_brd_mem_copy ======== 109 * Purpose: 110 * Copy memory from one DSP address to another 111 * Parameters: 112 * dev_context: Pointer to context handle 113 * dsp_dest_addr: DSP address to copy to 114 * dsp_src_addr: DSP address to copy from 115 * ul_num_bytes: Number of bytes to copy 116 * mem_type: What section of memory to copy to 117 * Returns: 118 * 0: Success. 119 * -EPERM: Other, unspecified error. 120 * Requires: 121 * dev_context != NULL 122 * Ensures: 123 * 0: Board is in BRD_RUNNING state. 124 * Interrupts to the PC are enabled. 125 * else: Board state is indeterminate. 126 */ 127 typedef int(*fxn_brd_memcopy) (struct bridge_dev_context 128 * dev_ctxt, 129 u32 dsp_dest_addr, 130 u32 dsp_src_addr, 131 u32 ul_num_bytes, u32 mem_type); 132 /* 133 * ======== bridge_brd_mem_write ======== 134 * Purpose: 135 * Write a block of host memory into a DSP address, into a given memory 136 * space. Unlike bridge_brd_write, this API does reset the DSP 137 * Parameters: 138 * dev_ctxt: Handle to Bridge driver defined device info. 139 * dsp_addr: Address on DSP board (Destination). 140 * host_buf: Pointer to host buffer (Source). 141 * ul_num_bytes: Number of bytes to transfer. 142 * mem_type: Memory space on DSP to which to transfer. 143 * Returns: 144 * 0: Success. 145 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 146 * -EPERM: Other, unspecified error. 147 * Requires: 148 * dev_ctxt != NULL; 149 * host_buf != NULL. 150 * Ensures: 151 */ 152 typedef int(*fxn_brd_memwrite) (struct bridge_dev_context 153 * dev_ctxt, 154 u8 *host_buf, 155 u32 dsp_addr, u32 ul_num_bytes, 156 u32 mem_type); 157 158 /* 159 * ======== bridge_brd_mem_map ======== 160 * Purpose: 161 * Map a MPU memory region to a DSP/IVA memory space 162 * Parameters: 163 * dev_ctxt: Handle to Bridge driver defined device info. 164 * ul_mpu_addr: MPU memory region start address. 165 * virt_addr: DSP/IVA memory region u8 address. 166 * ul_num_bytes: Number of bytes to map. 167 * map_attrs: Mapping attributes (e.g. endianness). 168 * Returns: 169 * 0: Success. 170 * -EPERM: Other, unspecified error. 171 * Requires: 172 * dev_ctxt != NULL; 173 * Ensures: 174 */ 175 typedef int(*fxn_brd_memmap) (struct bridge_dev_context 176 * dev_ctxt, u32 ul_mpu_addr, 177 u32 virt_addr, u32 ul_num_bytes, 178 u32 map_attr, 179 struct page **mapped_pages); 180 181 /* 182 * ======== bridge_brd_mem_un_map ======== 183 * Purpose: 184 * UnMap an MPU memory region from DSP/IVA memory space 185 * Parameters: 186 * dev_ctxt: Handle to Bridge driver defined device info. 187 * virt_addr: DSP/IVA memory region u8 address. 188 * ul_num_bytes: Number of bytes to unmap. 189 * Returns: 190 * 0: Success. 191 * -EPERM: Other, unspecified error. 192 * Requires: 193 * dev_ctxt != NULL; 194 * Ensures: 195 */ 196 typedef int(*fxn_brd_memunmap) (struct bridge_dev_context 197 * dev_ctxt, 198 u32 virt_addr, u32 ul_num_bytes); 199 200 /* 201 * ======== bridge_brd_stop ======== 202 * Purpose: 203 * Bring board to the BRD_STOPPED state. 204 * Parameters: 205 * dev_ctxt: Handle to Bridge driver defined device context. 206 * Returns: 207 * 0: Success. 208 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 209 * -EPERM: Other, unspecified error. 210 * Requires: 211 * dev_ctxt != NULL 212 * Ensures: 213 * 0: Board is in BRD_STOPPED (stop) state; 214 * Interrupts to the PC are disabled. 215 * else: Board state is indeterminate. 216 */ 217 typedef int(*fxn_brd_stop) (struct bridge_dev_context *dev_ctxt); 218 219 /* 220 * ======== bridge_brd_status ======== 221 * Purpose: 222 * Report the current state of the board. 223 * Parameters: 224 * dev_ctxt: Handle to Bridge driver defined device context. 225 * board_state: Ptr to BRD status variable. 226 * Returns: 227 * 0: 228 * Requires: 229 * board_state != NULL; 230 * dev_ctxt != NULL 231 * Ensures: 232 * *board_state is one of 233 * {BRD_STOPPED, BRD_IDLE, BRD_RUNNING, BRD_UNKNOWN}; 234 */ 235 typedef int(*fxn_brd_status) (struct bridge_dev_context *dev_ctxt, 236 int *board_state); 237 238 /* 239 * ======== bridge_brd_read ======== 240 * Purpose: 241 * Read a block of DSP memory, from a given memory space, into a host 242 * buffer. 243 * Parameters: 244 * dev_ctxt: Handle to Bridge driver defined device info. 245 * host_buf: Pointer to host buffer (Destination). 246 * dsp_addr: Address on DSP board (Source). 247 * ul_num_bytes: Number of bytes to transfer. 248 * mem_type: Memory space on DSP from which to transfer. 249 * Returns: 250 * 0: Success. 251 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 252 * -EPERM: Other, unspecified error. 253 * Requires: 254 * dev_ctxt != NULL; 255 * host_buf != NULL. 256 * Ensures: 257 * Will not write more than ul_num_bytes bytes into host_buf. 258 */ 259 typedef int(*fxn_brd_read) (struct bridge_dev_context *dev_ctxt, 260 u8 *host_buf, 261 u32 dsp_addr, 262 u32 ul_num_bytes, u32 mem_type); 263 264 /* 265 * ======== bridge_brd_write ======== 266 * Purpose: 267 * Write a block of host memory into a DSP address, into a given memory 268 * space. 269 * Parameters: 270 * dev_ctxt: Handle to Bridge driver defined device info. 271 * dsp_addr: Address on DSP board (Destination). 272 * host_buf: Pointer to host buffer (Source). 273 * ul_num_bytes: Number of bytes to transfer. 274 * mem_type: Memory space on DSP to which to transfer. 275 * Returns: 276 * 0: Success. 277 * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. 278 * -EPERM: Other, unspecified error. 279 * Requires: 280 * dev_ctxt != NULL; 281 * host_buf != NULL. 282 * Ensures: 283 */ 284 typedef int(*fxn_brd_write) (struct bridge_dev_context *dev_ctxt, 285 u8 *host_buf, 286 u32 dsp_addr, 287 u32 ul_num_bytes, u32 mem_type); 288 289 /* 290 * ======== bridge_chnl_create ======== 291 * Purpose: 292 * Create a channel manager object, responsible for opening new channels 293 * and closing old ones for a given 'Bridge board. 294 * Parameters: 295 * channel_mgr: Location to store a channel manager object on output. 296 * hdev_obj: Handle to a device object. 297 * mgr_attrts: Channel manager attributes. 298 * mgr_attrts->max_channels: Max channels 299 * mgr_attrts->birq: Channel's I/O IRQ number. 300 * mgr_attrts->irq_shared: TRUE if the IRQ is shareable. 301 * mgr_attrts->word_size: DSP Word size in equivalent PC bytes.. 302 * mgr_attrts->shm_base: Base physical address of shared memory, if any. 303 * mgr_attrts->sm_length: Bytes of shared memory block. 304 * Returns: 305 * 0: Success; 306 * -ENOMEM: Insufficient memory for requested resources. 307 * -EIO: Unable to plug ISR for given IRQ. 308 * -EFAULT: Couldn't map physical address to a virtual one. 309 * Requires: 310 * channel_mgr != NULL. 311 * mgr_attrts != NULL 312 * mgr_attrts field are all valid: 313 * 0 < max_channels <= CHNL_MAXCHANNELS. 314 * birq <= 15. 315 * word_size > 0. 316 * hdev_obj != NULL 317 * No channel manager exists for this board. 318 * Ensures: 319 */ 320 typedef int(*fxn_chnl_create) (struct chnl_mgr 321 **channel_mgr, 322 struct dev_object 323 * hdev_obj, 324 const struct 325 chnl_mgrattrs * mgr_attrts); 326 327 /* 328 * ======== bridge_chnl_destroy ======== 329 * Purpose: 330 * Close all open channels, and destroy the channel manager. 331 * Parameters: 332 * hchnl_mgr: Channel manager object. 333 * Returns: 334 * 0: Success. 335 * -EFAULT: hchnl_mgr was invalid. 336 * Requires: 337 * Ensures: 338 * 0: Cancels I/O on each open channel. Closes each open channel. 339 * chnl_create may subsequently be called for the same device. 340 */ 341 typedef int(*fxn_chnl_destroy) (struct chnl_mgr *hchnl_mgr); 342 /* 343 * ======== bridge_deh_notify ======== 344 * Purpose: 345 * When notified of DSP error, take appropriate action. 346 * Parameters: 347 * hdeh_mgr: Handle to DEH manager object. 348 * evnt_mask: Indicate the type of exception 349 * error_info: Error information 350 * Returns: 351 * 352 * Requires: 353 * hdeh_mgr != NULL; 354 * evnt_mask with a valid exception 355 * Ensures: 356 */ 357 typedef void (*fxn_deh_notify) (struct deh_mgr *hdeh_mgr, 358 u32 evnt_mask, u32 error_info); 359 360 /* 361 * ======== bridge_chnl_open ======== 362 * Purpose: 363 * Open a new half-duplex channel to the DSP board. 364 * Parameters: 365 * chnl: Location to store a channel object handle. 366 * hchnl_mgr: Handle to channel manager, as returned by 367 * CHNL_GetMgr(). 368 * chnl_mode: One of {CHNL_MODETODSP, CHNL_MODEFROMDSP} specifies 369 * direction of data transfer. 370 * ch_id: If CHNL_PICKFREE is specified, the channel manager will 371 * select a free channel id (default); 372 * otherwise this field specifies the id of the channel. 373 * pattrs: Channel attributes. Attribute fields are as follows: 374 * pattrs->uio_reqs: Specifies the maximum number of I/O requests which can 375 * be pending at any given time. All request packets are 376 * preallocated when the channel is opened. 377 * pattrs->event_obj: This field allows the user to supply an auto reset 378 * event object for channel I/O completion notifications. 379 * It is the responsibility of the user to destroy this 380 * object AFTER closing the channel. 381 * This channel event object can be retrieved using 382 * CHNL_GetEventHandle(). 383 * pattrs->hReserved: The kernel mode handle of this event object. 384 * 385 * Returns: 386 * 0: Success. 387 * -EFAULT: hchnl_mgr is invalid. 388 * -ENOMEM: Insufficient memory for requested resources. 389 * -EINVAL: Invalid number of IOReqs. 390 * -ENOSR: No free channels available. 391 * -ECHRNG: Channel ID is out of range. 392 * -EALREADY: Channel is in use. 393 * -EIO: No free IO request packets available for 394 * queuing. 395 * Requires: 396 * chnl != NULL. 397 * pattrs != NULL. 398 * pattrs->event_obj is a valid event handle. 399 * pattrs->hReserved is the kernel mode handle for pattrs->event_obj. 400 * Ensures: 401 * 0: *chnl is a valid channel. 402 * else: *chnl is set to NULL if (chnl != NULL); 403 */ 404 typedef int(*fxn_chnl_open) (struct chnl_object 405 **chnl, 406 struct chnl_mgr *hchnl_mgr, 407 s8 chnl_mode, 408 u32 ch_id, 409 const struct 410 chnl_attr * pattrs); 411 412 /* 413 * ======== bridge_chnl_close ======== 414 * Purpose: 415 * Ensures all pending I/O on this channel is cancelled, discards all 416 * queued I/O completion notifications, then frees the resources allocated 417 * for this channel, and makes the corresponding logical channel id 418 * available for subsequent use. 419 * Parameters: 420 * chnl_obj: Handle to a channel object. 421 * Returns: 422 * 0: Success; 423 * -EFAULT: Invalid chnl_obj. 424 * Requires: 425 * No thread must be blocked on this channel's I/O completion event. 426 * Ensures: 427 * 0: chnl_obj is no longer valid. 428 */ 429 typedef int(*fxn_chnl_close) (struct chnl_object *chnl_obj); 430 431 /* 432 * ======== bridge_chnl_add_io_req ======== 433 * Purpose: 434 * Enqueue an I/O request for data transfer on a channel to the DSP. 435 * The direction (mode) is specified in the channel object. Note the DSP 436 * address is specified for channels opened in direct I/O mode. 437 * Parameters: 438 * chnl_obj: Channel object handle. 439 * host_buf: Host buffer address source. 440 * byte_size: Number of PC bytes to transfer. A zero value indicates 441 * that this buffer is the last in the output channel. 442 * A zero value is invalid for an input channel. 443 *! buf_size: Actual buffer size in host bytes. 444 * dw_dsp_addr: DSP address for transfer. (Currently ignored). 445 * dw_arg: A user argument that travels with the buffer. 446 * Returns: 447 * 0: Success; 448 * -EFAULT: Invalid chnl_obj or host_buf. 449 * -EPERM: User cannot mark EOS on an input channel. 450 * -ECANCELED: I/O has been cancelled on this channel. No further 451 * I/O is allowed. 452 * -EPIPE: End of stream was already marked on a previous 453 * IORequest on this channel. No further I/O is expected. 454 * -EINVAL: Buffer submitted to this output channel is larger than 455 * the size of the physical shared memory output window. 456 * Requires: 457 * Ensures: 458 * 0: The buffer will be transferred if the channel is ready; 459 * otherwise, will be queued for transfer when the channel becomes 460 * ready. In any case, notifications of I/O completion are 461 * asynchronous. 462 * If byte_size is 0 for an output channel, subsequent CHNL_AddIOReq's 463 * on this channel will fail with error code -EPIPE. The 464 * corresponding IOC for this I/O request will have its status flag 465 * set to CHNL_IOCSTATEOS. 466 */ 467 typedef int(*fxn_chnl_addioreq) (struct chnl_object 468 * chnl_obj, 469 void *host_buf, 470 u32 byte_size, 471 u32 buf_size, 472 u32 dw_dsp_addr, u32 dw_arg); 473 474 /* 475 * ======== bridge_chnl_get_ioc ======== 476 * Purpose: 477 * Dequeue an I/O completion record, which contains information about the 478 * completed I/O request. 479 * Parameters: 480 * chnl_obj: Channel object handle. 481 * timeout: A value of CHNL_IOCNOWAIT will simply dequeue the 482 * first available IOC. 483 * chan_ioc: On output, contains host buffer address, bytes 484 * transferred, and status of I/O completion. 485 * chan_ioc->status: See chnldefs.h. 486 * Returns: 487 * 0: Success. 488 * -EFAULT: Invalid chnl_obj or chan_ioc. 489 * -EREMOTEIO: CHNL_IOCNOWAIT was specified as the timeout parameter 490 * yet no I/O completions were queued. 491 * Requires: 492 * timeout == CHNL_IOCNOWAIT. 493 * Ensures: 494 * 0: if there are any remaining IOC's queued before this call 495 * returns, the channel event object will be left in a signalled 496 * state. 497 */ 498 typedef int(*fxn_chnl_getioc) (struct chnl_object *chnl_obj, 499 u32 timeout, 500 struct chnl_ioc *chan_ioc); 501 502 /* 503 * ======== bridge_chnl_cancel_io ======== 504 * Purpose: 505 * Return all I/O requests to the client which have not yet been 506 * transferred. The channel's I/O completion object is 507 * signalled, and all the I/O requests are queued as IOC's, with the 508 * status field set to CHNL_IOCSTATCANCEL. 509 * This call is typically used in abort situations, and is a prelude to 510 * chnl_close(); 511 * Parameters: 512 * chnl_obj: Channel object handle. 513 * Returns: 514 * 0: Success; 515 * -EFAULT: Invalid chnl_obj. 516 * Requires: 517 * Ensures: 518 * Subsequent I/O requests to this channel will not be accepted. 519 */ 520 typedef int(*fxn_chnl_cancelio) (struct chnl_object *chnl_obj); 521 522 /* 523 * ======== bridge_chnl_flush_io ======== 524 * Purpose: 525 * For an output stream (to the DSP), indicates if any IO requests are in 526 * the output request queue. For input streams (from the DSP), will 527 * cancel all pending IO requests. 528 * Parameters: 529 * chnl_obj: Channel object handle. 530 * timeout: Timeout value for flush operation. 531 * Returns: 532 * 0: Success; 533 * S_CHNLIOREQUEST: Returned if any IORequests are in the output queue. 534 * -EFAULT: Invalid chnl_obj. 535 * Requires: 536 * Ensures: 537 * 0: No I/O requests will be pending on this channel. 538 */ 539 typedef int(*fxn_chnl_flushio) (struct chnl_object *chnl_obj, 540 u32 timeout); 541 542 /* 543 * ======== bridge_chnl_get_info ======== 544 * Purpose: 545 * Retrieve information related to a channel. 546 * Parameters: 547 * chnl_obj: Handle to a valid channel object, or NULL. 548 * channel_info: Location to store channel info. 549 * Returns: 550 * 0: Success; 551 * -EFAULT: Invalid chnl_obj or channel_info. 552 * Requires: 553 * Ensures: 554 * 0: channel_info points to a filled in chnl_info struct, 555 * if (channel_info != NULL). 556 */ 557 typedef int(*fxn_chnl_getinfo) (struct chnl_object *chnl_obj, 558 struct chnl_info *channel_info); 559 560 /* 561 * ======== bridge_chnl_get_mgr_info ======== 562 * Purpose: 563 * Retrieve information related to the channel manager. 564 * Parameters: 565 * hchnl_mgr: Handle to a valid channel manager, or NULL. 566 * ch_id: Channel ID. 567 * mgr_info: Location to store channel manager info. 568 * Returns: 569 * 0: Success; 570 * -EFAULT: Invalid hchnl_mgr or mgr_info. 571 * -ECHRNG: Invalid channel ID. 572 * Requires: 573 * Ensures: 574 * 0: mgr_info points to a filled in chnl_mgrinfo 575 * struct, if (mgr_info != NULL). 576 */ 577 typedef int(*fxn_chnl_getmgrinfo) (struct chnl_mgr 578 * hchnl_mgr, 579 u32 ch_id, 580 struct chnl_mgrinfo *mgr_info); 581 582 /* 583 * ======== bridge_chnl_idle ======== 584 * Purpose: 585 * Idle a channel. If this is an input channel, or if this is an output 586 * channel and flush_data is TRUE, all currently enqueued buffers will be 587 * dequeued (data discarded for output channel). 588 * If this is an output channel and flush_data is FALSE, this function 589 * will block until all currently buffered data is output, or the timeout 590 * specified has been reached. 591 * 592 * Parameters: 593 * chnl_obj: Channel object handle. 594 * timeout: If output channel and flush_data is FALSE, timeout value 595 * to wait for buffers to be output. (Not used for 596 * input channel). 597 * flush_data: If output channel and flush_data is TRUE, discard any 598 * currently buffered data. If FALSE, wait for currently 599 * buffered data to be output, or timeout, whichever 600 * occurs first. flush_data is ignored for input channel. 601 * Returns: 602 * 0: Success; 603 * -EFAULT: Invalid chnl_obj. 604 * -ETIMEDOUT: Timeout occurred before channel could be idled. 605 * Requires: 606 * Ensures: 607 */ 608 typedef int(*fxn_chnl_idle) (struct chnl_object *chnl_obj, 609 u32 timeout, bool flush_data); 610 611 /* 612 * ======== bridge_chnl_register_notify ======== 613 * Purpose: 614 * Register for notification of events on a channel. 615 * Parameters: 616 * chnl_obj: Channel object handle. 617 * event_mask: Type of events to be notified about: IO completion 618 * (DSP_STREAMIOCOMPLETION) or end of stream 619 * (DSP_STREAMDONE). 620 * notify_type: DSP_SIGNALEVENT. 621 * hnotification: Handle of a dsp_notification object. 622 * Returns: 623 * 0: Success. 624 * -ENOMEM: Insufficient memory. 625 * -EINVAL: event_mask is 0 and hnotification was not 626 * previously registered. 627 * -EFAULT: NULL hnotification, hnotification event name 628 * too long, or hnotification event name NULL. 629 * Requires: 630 * Valid chnl_obj. 631 * hnotification != NULL. 632 * (event_mask & ~(DSP_STREAMIOCOMPLETION | DSP_STREAMDONE)) == 0. 633 * notify_type == DSP_SIGNALEVENT. 634 * Ensures: 635 */ 636 typedef int(*fxn_chnl_registernotify) 637 (struct chnl_object *chnl_obj, 638 u32 event_mask, u32 notify_type, struct dsp_notification *hnotification); 639 640 /* 641 * ======== bridge_dev_create ======== 642 * Purpose: 643 * Complete creation of the device object for this board. 644 * Parameters: 645 * device_ctx: Ptr to location to store a Bridge device context. 646 * hdev_obj: Handle to a Device Object, created and managed by DSP API. 647 * config_param: Ptr to configuration parameters provided by the 648 * Configuration Manager during device loading. 649 * pDspConfig: DSP resources, as specified in the registry key for this 650 * device. 651 * Returns: 652 * 0: Success. 653 * -ENOMEM: Unable to allocate memory for device context. 654 * Requires: 655 * device_ctx != NULL; 656 * hdev_obj != NULL; 657 * config_param != NULL; 658 * pDspConfig != NULL; 659 * Fields in config_param and pDspConfig contain valid values. 660 * Ensures: 661 * 0: All Bridge driver specific DSP resource and other 662 * board context has been allocated. 663 * -ENOMEM: Bridge failed to allocate resources. 664 * Any acquired resources have been freed. The DSP API 665 * will not call bridge_dev_destroy() if 666 * bridge_dev_create() fails. 667 * Details: 668 * Called during the CONFIGMG's Device_Init phase. Based on host and 669 * DSP configuration information, create a board context, a handle to 670 * which is passed into other Bridge BRD and CHNL functions. The 671 * board context contains state information for the device. Since the 672 * addresses of all pointer parameters may be invalid when this 673 * function returns, they must not be stored into the device context 674 * structure. 675 */ 676 typedef int(*fxn_dev_create) (struct bridge_dev_context 677 **device_ctx, 678 struct dev_object 679 * hdev_obj, 680 struct cfg_hostres 681 * config_param); 682 683 /* 684 * ======== bridge_dev_ctrl ======== 685 * Purpose: 686 * Bridge driver specific interface. 687 * Parameters: 688 * dev_ctxt: Handle to Bridge driver defined device info. 689 * dw_cmd: Bridge driver defined command code. 690 * pargs: Pointer to an arbitrary argument structure. 691 * Returns: 692 * 0 or -EPERM. Actual command error codes should be passed back in 693 * the pargs structure, and are defined by the Bridge driver implementor. 694 * Requires: 695 * All calls are currently assumed to be synchronous. There are no 696 * IOCTL completion routines provided. 697 * Ensures: 698 */ 699 typedef int(*fxn_dev_ctrl) (struct bridge_dev_context *dev_ctxt, 700 u32 dw_cmd, void *pargs); 701 702 /* 703 * ======== bridge_dev_destroy ======== 704 * Purpose: 705 * Deallocate Bridge device extension structures and all other resources 706 * acquired by the Bridge driver. 707 * No calls to other Bridge driver functions may subsequently 708 * occur, except for bridge_dev_create(). 709 * Parameters: 710 * dev_ctxt: Handle to Bridge driver defined device information. 711 * Returns: 712 * 0: Success. 713 * -EPERM: Failed to release a resource previously acquired. 714 * Requires: 715 * dev_ctxt != NULL; 716 * Ensures: 717 * 0: Device context is freed. 718 */ 719 typedef int(*fxn_dev_destroy) (struct bridge_dev_context *dev_ctxt); 720 721 /* 722 * ======== bridge_io_create ======== 723 * Purpose: 724 * Create an object that manages I/O between CHNL and msg_ctrl. 725 * Parameters: 726 * io_man: Location to store IO manager on output. 727 * hchnl_mgr: Handle to channel manager. 728 * hmsg_mgr: Handle to message manager. 729 * Returns: 730 * 0: Success. 731 * -ENOMEM: Memory allocation failure. 732 * -EPERM: Creation failed. 733 * Requires: 734 * hdev_obj != NULL; 735 * Channel manager already created; 736 * Message manager already created; 737 * mgr_attrts != NULL; 738 * io_man != NULL; 739 * Ensures: 740 */ 741 typedef int(*fxn_io_create) (struct io_mgr **io_man, 742 struct dev_object *hdev_obj, 743 const struct io_attrs *mgr_attrts); 744 745 /* 746 * ======== bridge_io_destroy ======== 747 * Purpose: 748 * Destroy object created in bridge_io_create. 749 * Parameters: 750 * hio_mgr: IO Manager. 751 * Returns: 752 * 0: Success. 753 * -ENOMEM: Memory allocation failure. 754 * -EPERM: Creation failed. 755 * Requires: 756 * Valid hio_mgr; 757 * Ensures: 758 */ 759 typedef int(*fxn_io_destroy) (struct io_mgr *hio_mgr); 760 761 /* 762 * ======== bridge_io_on_loaded ======== 763 * Purpose: 764 * Called whenever a program is loaded to update internal data. For 765 * example, if shared memory is used, this function would update the 766 * shared memory location and address. 767 * Parameters: 768 * hio_mgr: IO Manager. 769 * Returns: 770 * 0: Success. 771 * -EPERM: Internal failure occurred. 772 * Requires: 773 * Valid hio_mgr; 774 * Ensures: 775 */ 776 typedef int(*fxn_io_onloaded) (struct io_mgr *hio_mgr); 777 778 /* 779 * ======== fxn_io_getprocload ======== 780 * Purpose: 781 * Called to get the Processor's current and predicted load 782 * Parameters: 783 * hio_mgr: IO Manager. 784 * proc_load_stat Processor Load statistics 785 * Returns: 786 * 0: Success. 787 * -EPERM: Internal failure occurred. 788 * Requires: 789 * Valid hio_mgr; 790 * Ensures: 791 */ 792 typedef int(*fxn_io_getprocload) (struct io_mgr *hio_mgr, 793 struct dsp_procloadstat * 794 proc_load_stat); 795 796 /* 797 * ======== bridge_msg_create ======== 798 * Purpose: 799 * Create an object to manage message queues. Only one of these objects 800 * can exist per device object. 801 * Parameters: 802 * msg_man: Location to store msg_ctrl manager on output. 803 * hdev_obj: Handle to a device object. 804 * msg_callback: Called whenever an RMS_EXIT message is received. 805 * Returns: 806 * 0: Success. 807 * -ENOMEM: Insufficient memory. 808 * Requires: 809 * msg_man != NULL. 810 * msg_callback != NULL. 811 * hdev_obj != NULL. 812 * Ensures: 813 */ 814 typedef int(*fxn_msg_create) 815 (struct msg_mgr **msg_man, 816 struct dev_object *hdev_obj, msg_onexit msg_callback); 817 818 /* 819 * ======== bridge_msg_create_queue ======== 820 * Purpose: 821 * Create a msg_ctrl queue for sending or receiving messages from a Message 822 * node on the DSP. 823 * Parameters: 824 * hmsg_mgr: msg_ctrl queue manager handle returned from 825 * bridge_msg_create. 826 * msgq: Location to store msg_ctrl queue on output. 827 * msgq_id: Identifier for messages (node environment pointer). 828 * max_msgs: Max number of simultaneous messages for the node. 829 * h: Handle passed to hmsg_mgr->msg_callback(). 830 * Returns: 831 * 0: Success. 832 * -ENOMEM: Insufficient memory. 833 * Requires: 834 * msgq != NULL. 835 * h != NULL. 836 * max_msgs > 0. 837 * Ensures: 838 * msgq !=NULL <==> 0. 839 */ 840 typedef int(*fxn_msg_createqueue) 841 (struct msg_mgr *hmsg_mgr, 842 struct msg_queue **msgq, u32 msgq_id, u32 max_msgs, void *h); 843 844 /* 845 * ======== bridge_msg_delete ======== 846 * Purpose: 847 * Delete a msg_ctrl manager allocated in bridge_msg_create(). 848 * Parameters: 849 * hmsg_mgr: Handle returned from bridge_msg_create(). 850 * Returns: 851 * Requires: 852 * Valid hmsg_mgr. 853 * Ensures: 854 */ 855 typedef void (*fxn_msg_delete) (struct msg_mgr *hmsg_mgr); 856 857 /* 858 * ======== bridge_msg_delete_queue ======== 859 * Purpose: 860 * Delete a msg_ctrl queue allocated in bridge_msg_create_queue. 861 * Parameters: 862 * msg_queue_obj: Handle to msg_ctrl queue returned from 863 * bridge_msg_create_queue. 864 * Returns: 865 * Requires: 866 * Valid msg_queue_obj. 867 * Ensures: 868 */ 869 typedef void (*fxn_msg_deletequeue) (struct msg_queue *msg_queue_obj); 870 871 /* 872 * ======== bridge_msg_get ======== 873 * Purpose: 874 * Get a message from a msg_ctrl queue. 875 * Parameters: 876 * msg_queue_obj: Handle to msg_ctrl queue returned from 877 * bridge_msg_create_queue. 878 * pmsg: Location to copy message into. 879 * utimeout: Timeout to wait for a message. 880 * Returns: 881 * 0: Success. 882 * -ETIME: Timeout occurred. 883 * -EPERM: No frames available for message (max_msgs too 884 * small). 885 * Requires: 886 * Valid msg_queue_obj. 887 * pmsg != NULL. 888 * Ensures: 889 */ 890 typedef int(*fxn_msg_get) (struct msg_queue *msg_queue_obj, 891 struct dsp_msg *pmsg, u32 utimeout); 892 893 /* 894 * ======== bridge_msg_put ======== 895 * Purpose: 896 * Put a message onto a msg_ctrl queue. 897 * Parameters: 898 * msg_queue_obj: Handle to msg_ctrl queue returned from 899 * bridge_msg_create_queue. 900 * pmsg: Pointer to message. 901 * utimeout: Timeout to wait for a message. 902 * Returns: 903 * 0: Success. 904 * -ETIME: Timeout occurred. 905 * -EPERM: No frames available for message (max_msgs too 906 * small). 907 * Requires: 908 * Valid msg_queue_obj. 909 * pmsg != NULL. 910 * Ensures: 911 */ 912 typedef int(*fxn_msg_put) (struct msg_queue *msg_queue_obj, 913 const struct dsp_msg *pmsg, u32 utimeout); 914 915 /* 916 * ======== bridge_msg_register_notify ======== 917 * Purpose: 918 * Register notification for when a message is ready. 919 * Parameters: 920 * msg_queue_obj: Handle to msg_ctrl queue returned from 921 * bridge_msg_create_queue. 922 * event_mask: Type of events to be notified about: Must be 923 * DSP_NODEMESSAGEREADY, or 0 to unregister. 924 * notify_type: DSP_SIGNALEVENT. 925 * hnotification: Handle of notification object. 926 * Returns: 927 * 0: Success. 928 * -ENOMEM: Insufficient memory. 929 * Requires: 930 * Valid msg_queue_obj. 931 * hnotification != NULL. 932 * notify_type == DSP_SIGNALEVENT. 933 * event_mask == DSP_NODEMESSAGEREADY || event_mask == 0. 934 * Ensures: 935 */ 936 typedef int(*fxn_msg_registernotify) 937 (struct msg_queue *msg_queue_obj, 938 u32 event_mask, u32 notify_type, struct dsp_notification *hnotification); 939 940 /* 941 * ======== bridge_msg_set_queue_id ======== 942 * Purpose: 943 * Set message queue id to node environment. Allows bridge_msg_create_queue 944 * to be called in node_allocate, before the node environment is known. 945 * Parameters: 946 * msg_queue_obj: Handle to msg_ctrl queue returned from 947 * bridge_msg_create_queue. 948 * msgq_id: Node environment pointer. 949 * Returns: 950 * Requires: 951 * Valid msg_queue_obj. 952 * msgq_id != 0. 953 * Ensures: 954 */ 955 typedef void (*fxn_msg_setqueueid) (struct msg_queue *msg_queue_obj, 956 u32 msgq_id); 957 958 /* 959 * Bridge Driver interface function table. 960 * 961 * The information in this table is filled in by the specific Bridge driver, 962 * and copied into the DSP API's own space. If any interface 963 * function field is set to a value of NULL, then the DSP API will 964 * consider that function not implemented, and return the error code 965 * -ENOSYS when a Bridge driver client attempts to call that function. 966 * 967 * This function table contains DSP API version numbers, which are used by the 968 * Bridge driver loader to help ensure backwards compatility between older 969 * Bridge drivers and newer DSP API. These must be set to 970 * BRD_API_MAJOR_VERSION and BRD_API_MINOR_VERSION, respectively. 971 * 972 * A Bridge driver need not export a CHNL interface. In this case, *all* of 973 * the bridge_chnl_* entries must be set to NULL. 974 */ 975 struct bridge_drv_interface { 976 u32 brd_api_major_version; /* Set to BRD_API_MAJOR_VERSION. */ 977 u32 brd_api_minor_version; /* Set to BRD_API_MINOR_VERSION. */ 978 fxn_dev_create dev_create; /* Create device context */ 979 fxn_dev_destroy dev_destroy; /* Destroy device context */ 980 fxn_dev_ctrl dev_cntrl; /* Optional vendor interface */ 981 fxn_brd_monitor brd_monitor; /* Load and/or start monitor */ 982 fxn_brd_start brd_start; /* Start DSP program. */ 983 fxn_brd_stop brd_stop; /* Stop/reset board. */ 984 fxn_brd_status brd_status; /* Get current board status. */ 985 fxn_brd_read brd_read; /* Read board memory */ 986 fxn_brd_write brd_write; /* Write board memory. */ 987 fxn_brd_setstate brd_set_state; /* Sets the Board State */ 988 fxn_brd_memcopy brd_mem_copy; /* Copies DSP Memory */ 989 fxn_brd_memwrite brd_mem_write; /* Write DSP Memory w/o halt */ 990 fxn_brd_memmap brd_mem_map; /* Maps MPU mem to DSP mem */ 991 fxn_brd_memunmap brd_mem_un_map; /* Unmaps MPU mem to DSP mem */ 992 fxn_chnl_create chnl_create; /* Create channel manager. */ 993 fxn_chnl_destroy chnl_destroy; /* Destroy channel manager. */ 994 fxn_chnl_open chnl_open; /* Create a new channel. */ 995 fxn_chnl_close chnl_close; /* Close a channel. */ 996 fxn_chnl_addioreq chnl_add_io_req; /* Req I/O on a channel. */ 997 fxn_chnl_getioc chnl_get_ioc; /* Wait for I/O completion. */ 998 fxn_chnl_cancelio chnl_cancel_io; /* Cancl I/O on a channel. */ 999 fxn_chnl_flushio chnl_flush_io; /* Flush I/O. */ 1000 fxn_chnl_getinfo chnl_get_info; /* Get channel specific info */ 1001 /* Get channel manager info. */ 1002 fxn_chnl_getmgrinfo chnl_get_mgr_info; 1003 fxn_chnl_idle chnl_idle; /* Idle the channel */ 1004 /* Register for notif. */ 1005 fxn_chnl_registernotify chnl_register_notify; 1006 fxn_io_create io_create; /* Create IO manager */ 1007 fxn_io_destroy io_destroy; /* Destroy IO manager */ 1008 fxn_io_onloaded io_on_loaded; /* Notify of program loaded */ 1009 /* Get Processor's current and predicted load */ 1010 fxn_io_getprocload io_get_proc_load; 1011 fxn_msg_create msg_create; /* Create message manager */ 1012 /* Create message queue */ 1013 fxn_msg_createqueue msg_create_queue; 1014 fxn_msg_delete msg_delete; /* Delete message manager */ 1015 /* Delete message queue */ 1016 fxn_msg_deletequeue msg_delete_queue; 1017 fxn_msg_get msg_get; /* Get a message */ 1018 fxn_msg_put msg_put; /* Send a message */ 1019 /* Register for notif. */ 1020 fxn_msg_registernotify msg_register_notify; 1021 /* Set message queue id */ 1022 fxn_msg_setqueueid msg_set_queue_id; 1023 }; 1024 1025 /* 1026 * ======== bridge_drv_entry ======== 1027 * Purpose: 1028 * Registers Bridge driver functions with the DSP API. Called only once 1029 * by the DSP API. The caller will first check DSP API version 1030 * compatibility, and then copy the interface functions into its own 1031 * memory space. 1032 * Parameters: 1033 * drv_intf Pointer to a location to receive a pointer to the 1034 * Bridge driver interface. 1035 * Returns: 1036 * Requires: 1037 * The code segment this function resides in must expect to be discarded 1038 * after completion. 1039 * Ensures: 1040 * drv_intf pointer initialized to Bridge driver's function 1041 * interface. No system resources are acquired by this function. 1042 * Details: 1043 * Called during the Device_Init phase. 1044 */ 1045 void bridge_drv_entry(struct bridge_drv_interface **drv_intf, 1046 const char *driver_file_name); 1047 1048 #endif /* DSPDEFS_ */ 1049