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