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