drivers/staging/tidspbridge/include/dspbridge/proc.h

   1 /*
   2  * proc.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * This is the DSP API RM module interface.
   7  *
   8  * Copyright (C) 2005-2006 Texas Instruments, Inc.
   9  *
  10  * This package is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License version 2 as
  12  * published by the Free Software Foundation.
  13  *
  14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17  */
  18
  19 #ifndef PROC_
  20 #define PROC_
  21
  22 #include <dspbridge/cfgdefs.h>
  23 #include <dspbridge/devdefs.h>
  24 #include <dspbridge/drv.h>
  25
  26 extern char *iva_img;
  27
  28 /*
  29  *  ======== proc_attach ========
  30  *  Purpose:
  31  *      Prepare for communication with a particular DSP processor, and return
  32  *      a handle to the processor object. The PROC Object gets created
  33  *  Parameters:
  34  *      processor_id  :    The processor index (zero-based).
  35  *      hmgr_obj  :        Handle to the Manager Object
  36  *      attr_in     :      Ptr to the dsp_processorattrin structure.
  37  *                            A NULL value means use default values.
  38  *      ph_processor :     Ptr to location to store processor handle.
  39  *  Returns:
  40  *      0     :    Success.
  41  *      -EPERM   :         General failure.
  42  *      -EFAULT :          Invalid processor handle.
  43  *      0:   Success; Processor already attached.
  44  *  Requires:
  45  *      ph_processor != NULL.
  46  *      PROC Initialized.
  47  *  Ensures:
  48  *      -EPERM, and *ph_processor == NULL, OR
  49  *      Success and *ph_processor is a Valid Processor handle OR
  50  *      0 and *ph_processor is a Valid Processor.
  51  *  Details:
  52  *      When attr_in is NULL, the default timeout value is 10 seconds.
  53  */
  54 extern int proc_attach(u32 processor_id,
  55                               const struct dsp_processorattrin
  56                               *attr_in, void **ph_processor,
  57                               struct process_context *pr_ctxt);
  58
  59 /*
  60  *  ======== proc_auto_start =========
  61  *  Purpose:
  62  *      A Particular device gets loaded with the default image
  63  *      if the AutoStart flag is set.
  64  *  Parameters:
  65  *      hdev_obj  :   Handle to the Device
  66  *  Returns:
  67  *      0     :   On Successful Loading
  68  *      -ENOENT   :   No DSP exec file found.
  69  *      -EPERM   :   General Failure
  70  *  Requires:
  71  *      hdev_obj != NULL.
  72  *      dev_node_obj != NULL.
  73  *      PROC Initialized.
  74  *  Ensures:
  75  */
  76 extern int proc_auto_start(struct cfg_devnode *dev_node_obj,
  77                                   struct dev_object *hdev_obj);
  78
  79 /*
  80  *  ======== proc_ctrl ========
  81  *  Purpose:
  82  *      Pass control information to the GPP device driver managing the DSP
  83  *      processor. This will be an OEM-only function, and not part of the
  84  *      'Bridge application developer's API.
  85  *  Parameters:
  86  *      hprocessor  :       The processor handle.
  87  *      dw_cmd       :       Private driver IOCTL cmd ID.
  88  *      pargs       :       Ptr to an driver defined argument structure.
  89  *  Returns:
  90  *      0     :       SUCCESS
  91  *      -EFAULT :       Invalid processor handle.
  92  *      -ETIME:       A Timeout Occured before the Control information
  93  *                        could be sent.
  94  *      -EPERM   :       General Failure.
  95  *  Requires:
  96  *      PROC Initialized.
  97  *  Ensures
  98  *  Details:
  99  *      This function Calls bridge_dev_ctrl.
 100  */
 101 extern int proc_ctrl(void *hprocessor,
 102                             u32 dw_cmd, struct dsp_cbdata *arg);
 103
 104 /*
 105  *  ======== proc_detach ========
 106  *  Purpose:
 107  *      Close a DSP processor and de-allocate all (GPP) resources reserved
 108  *      for it. The Processor Object is deleted.
 109  *  Parameters:
 110  *      pr_ctxt     :   The processor handle.
 111  *  Returns:
 112  *      0     :   Success.
 113  *      -EFAULT :   InValid Handle.
 114  *      -EPERM   :   General failure.
 115  *  Requires:
 116  *      PROC Initialized.
 117  *  Ensures:
 118  *      PROC Object is destroyed.
 119  */
 120 extern int proc_detach(struct process_context *pr_ctxt);
 121
 122 /*
 123  *  ======== proc_enum_nodes ========
 124  *  Purpose:
 125  *      Enumerate the nodes currently allocated on a processor.
 126  *  Parameters:
 127  *      hprocessor  :   The processor handle.
 128  *      node_tab    :   The first Location of an array allocated for node
 129  *                    handles.
 130  *      node_tab_size:   The number of (DSP_HNODE) handles that can be held
 131  *                    to the memory the client has allocated for node_tab
 132  *      pu_num_nodes  :   Location where DSPProcessor_EnumNodes will return
 133  *                    the number of valid handles written to node_tab
 134  *      pu_allocated :   Location where DSPProcessor_EnumNodes will return
 135  *                    the number of nodes that are allocated on the DSP.
 136  *  Returns:
 137  *      0     :   Success.
 138  *      -EFAULT :   Invalid processor handle.
 139  *      -EINVAL   :   The amount of memory allocated for node_tab is
 140  *                    insufficent. That is the number of nodes actually
 141  *                    allocated on the DSP is greater than the value
 142  *                    specified for node_tab_size.
 143  *      -EPERM   :   Unable to get Resource Information.
 144  *  Details:
 145  *  Requires
 146  *      pu_num_nodes is not NULL.
 147  *      pu_allocated is not NULL.
 148  *      node_tab is not NULL.
 149  *      PROC Initialized.
 150  *  Ensures:
 151  *  Details:
 152  */
 153 extern int proc_enum_nodes(void *hprocessor,
 154                                   void **node_tab,
 155                                   u32 node_tab_size,
 156                                   u32 *pu_num_nodes,
 157                                   u32 *pu_allocated);
 158
 159 /*
 160  *  ======== proc_get_resource_info ========
 161  *  Purpose:
 162  *      Enumerate the resources currently available on a processor.
 163  *  Parameters:
 164  *      hprocessor  :       The processor handle.
 165  *      resource_type:      Type of resource .
 166  *      resource_info:      Ptr to the dsp_resourceinfo structure.
 167  *      resource_info_size:  Size of the structure.
 168  *  Returns:
 169  *      0     :       Success.
 170  *      -EFAULT :       Invalid processor handle.
 171  *      -EBADR:    The processor is not in the PROC_RUNNING state.
 172  *      -ETIME:       A timeout occured before the DSP responded to the
 173  *                        querry.
 174  *      -EPERM   :       Unable to get Resource Information
 175  *  Requires:
 176  *      resource_info is not NULL.
 177  *      Parameter resource_type is Valid.[TBD]
 178  *      resource_info_size is >= sizeof dsp_resourceinfo struct.
 179  *      PROC Initialized.
 180  *  Ensures:
 181  *  Details:
 182  *      This function currently returns
 183  *      -ENOSYS, and does not write any data to the resource_info struct.
 184  */
 185 extern int proc_get_resource_info(void *hprocessor,
 186                                          u32 resource_type,
 187                                          struct dsp_resourceinfo
 188                                          *resource_info,
 189                                          u32 resource_info_size);
 190
 191 /*
 192  *  ======== proc_exit ========
 193  *  Purpose:
 194  *      Decrement reference count, and free resources when reference count is
 195  *      0.
 196  *  Parameters:
 197  *  Returns:
 198  *  Requires:
 199  *      PROC is initialized.
 200  *  Ensures:
 201  *      When reference count == 0, PROC's private resources are freed.
 202  */
 203 extern void proc_exit(void);
 204
 205 /*
 206  * ======== proc_get_dev_object =========
 207  *  Purpose:
 208  *      Returns the DEV Hanlde for a given Processor handle
 209  *  Parameters:
 210  *      hprocessor  :   Processor Handle
 211  *      device_obj :    Location to store the DEV Handle.
 212  *  Returns:
 213  *      0     :   Success; *device_obj has Dev handle
 214  *      -EPERM   :   Failure; *device_obj is zero.
 215  *  Requires:
 216  *      device_obj is not NULL
 217  *      PROC Initialized.
 218  *  Ensures:
 219  *      0     :   *device_obj is not NULL
 220  *      -EPERM   :   *device_obj is NULL.
 221  */
 222 extern int proc_get_dev_object(void *hprocessor,
 223                                       struct dev_object **device_obj);
 224
 225 /*
 226  *  ======== proc_init ========
 227  *  Purpose:
 228  *      Initialize PROC's private state, keeping a reference count on each
 229  *      call.
 230  *  Parameters:
 231  *  Returns:
 232  *      TRUE if initialized; FALSE if error occured.
 233  *  Requires:
 234  *  Ensures:
 235  *      TRUE: A requirement for the other public PROC functions.
 236  */
 237 extern bool proc_init(void);
 238
 239 /*
 240  *  ======== proc_get_state ========
 241  *  Purpose:
 242  *      Report the state of the specified DSP processor.
 243  *  Parameters:
 244  *      hprocessor  :   The processor handle.
 245  *      proc_state_obj :   Ptr to location to store the dsp_processorstate
 246  *                    structure.
 247  *      state_info_size: Size of dsp_processorstate.
 248  *  Returns:
 249  *      0     :   Success.
 250  *      -EFAULT :   Invalid processor handle.
 251  *      -EPERM   :   General failure while querying processor state.
 252  *  Requires:
 253  *      proc_state_obj is not NULL
 254  *      state_info_size is >= than the size of dsp_processorstate structure.
 255  *      PROC Initialized.
 256  *  Ensures:
 257  *  Details:
 258  */
 259 extern int proc_get_state(void *hprocessor, struct dsp_processorstate
 260                                  *proc_state_obj, u32 state_info_size);
 261
 262 /*
 263  *  ======== PROC_GetProcessorID ========
 264  *  Purpose:
 265  *      Report the state of the specified DSP processor.
 266  *  Parameters:
 267  *      hprocessor  :   The processor handle.
 268  *      proc_id      :   Processor ID
 269  *
 270  *  Returns:
 271  *      0     :   Success.
 272  *      -EFAULT :   Invalid processor handle.
 273  *      -EPERM   :   General failure while querying processor state.
 274  *  Requires:
 275  *      proc_state_obj is not NULL
 276  *      state_info_size is >= than the size of dsp_processorstate structure.
 277  *      PROC Initialized.
 278  *  Ensures:
 279  *  Details:
 280  */
 281 extern int proc_get_processor_id(void *proc, u32 * proc_id);
 282
 283 /*
 284  *  ======== proc_get_trace ========
 285  *  Purpose:
 286  *      Retrieve the trace buffer from the specified DSP processor.
 287  *  Parameters:
 288  *      hprocessor  :   The processor handle.
 289  *      pbuf    :   Ptr to buffer to hold trace output.
 290  *      max_size    :   Maximum size of the output buffer.
 291  *  Returns:
 292  *      0     :   Success.
 293  *      -EFAULT :   Invalid processor handle.
 294  *      -EPERM   :   General failure while retireving processor trace
 295  *                    Buffer.
 296  *  Requires:
 297  *      pbuf is not NULL
 298  *      max_size is > 0.
 299  *      PROC Initialized.
 300  *  Ensures:
 301  *  Details:
 302  */
 303 extern int proc_get_trace(void *hprocessor, u8 * pbuf, u32 max_size);
 304
 305 /*
 306  *  ======== proc_load ========
 307  *  Purpose:
 308  *      Reset a processor and load a new base program image.
 309  *      This will be an OEM-only function.
 310  *  Parameters:
 311  *      hprocessor:       The processor handle.
 312  *      argc_index:       The number of Arguments(strings)in the aArgV[]
 313  *      user_args:       An Array of Arguments(Unicode Strings)
 314  *      user_envp:       An Array of Environment settings(Unicode Strings)
 315  *  Returns:
 316  *      0:       Success.
 317  *      -ENOENT:       The DSP Execuetable was not found.
 318  *      -EFAULT:       Invalid processor handle.
 319  *      -EPERM   :       Unable to Load the Processor
 320  *  Requires:
 321  *      user_args is not NULL
 322  *      argc_index is > 0
 323  *      PROC Initialized.
 324  *  Ensures:
 325  *      Success and ProcState == PROC_LOADED
 326  *      or DSP_FAILED status.
 327  *  Details:
 328  *      Does not implement access rights to control which GPP application
 329  *      can load the processor.
 330  */
 331 extern int proc_load(void *hprocessor,
 332                             const s32 argc_index, const char **user_args,
 333                             const char **user_envp);
 334
 335 /*
 336  *  ======== proc_register_notify ========
 337  *  Purpose:
 338  *      Register to be notified of specific processor events
 339  *  Parameters:
 340  *      hprocessor  :   The processor handle.
 341  *      event_mask  :   Mask of types of events to be notified about.
 342  *      notify_type :   Type of notification to be sent.
 343  *      hnotification:  Handle to be used for notification.
 344  *  Returns:
 345  *      0     :   Success.
 346  *      -EFAULT :   Invalid processor handle or hnotification.
 347  *      -EINVAL  :   Parameter event_mask is Invalid
 348  *      DSP_ENOTIMP :   The notification type specified in uNotifyMask
 349  *                    is not supported.
 350  *      -EPERM   :   Unable to register for notification.
 351  *  Requires:
 352  *      hnotification is not NULL
 353  *      PROC Initialized.
 354  *  Ensures:
 355  *  Details:
 356  */
 357 extern int proc_register_notify(void *hprocessor,
 358                                        u32 event_mask, u32 notify_type,
 359                                        struct dsp_notification
 360                                        *hnotification);
 361
 362 /*
 363  *  ======== proc_notify_clients ========
 364  *  Purpose:
 365  *      Notify the Processor Clients
 366  *  Parameters:
 367  *      proc       :   The processor handle.
 368  *      events     :   Event to be notified about.
 369  *  Returns:
 370  *      0     :   Success.
 371  *      -EFAULT :   Invalid processor handle.
 372  *      -EPERM   :   Failure to Set or Reset the Event
 373  *  Requires:
 374  *      events is Supported or Valid type of Event
 375  *      proc is a valid handle
 376  *      PROC Initialized.
 377  *  Ensures:
 378  */
 379 extern int proc_notify_clients(void *proc, u32 events);
 380
 381 /*
 382  *  ======== proc_notify_all_clients ========
 383  *  Purpose:
 384  *      Notify the Processor Clients
 385  *  Parameters:
 386  *      proc       :   The processor handle.
 387  *      events     :   Event to be notified about.
 388  *  Returns:
 389  *      0     :   Success.
 390  *      -EFAULT :   Invalid processor handle.
 391  *      -EPERM   :   Failure to Set or Reset the Event
 392  *  Requires:
 393  *      events is Supported or Valid type of Event
 394  *      proc is a valid handle
 395  *      PROC Initialized.
 396  *  Ensures:
 397  *  Details:
 398  *      NODE And STRM would use this function to notify their clients
 399  *      about the state changes in NODE or STRM.
 400  */
 401 extern int proc_notify_all_clients(void *proc, u32 events);
 402
 403 /*
 404  *  ======== proc_start ========
 405  *  Purpose:
 406  *      Start a processor running.
 407  *      Processor must be in PROC_LOADED state.
 408  *      This will be an OEM-only function, and not part of the 'Bridge
 409  *      application developer's API.
 410  *  Parameters:
 411  *      hprocessor  :       The processor handle.
 412  *  Returns:
 413  *      0     :       Success.
 414  *      -EFAULT :       Invalid processor handle.
 415  *      -EBADR:    Processor is not in PROC_LOADED state.
 416  *      -EPERM   :       Unable to start the processor.
 417  *  Requires:
 418  *      PROC Initialized.
 419  *  Ensures:
 420  *      Success and ProcState == PROC_RUNNING or DSP_FAILED status.
 421  *  Details:
 422  */
 423 extern int proc_start(void *hprocessor);
 424
 425 /*
 426  *  ======== proc_stop ========
 427  *  Purpose:
 428  *      Start a processor running.
 429  *      Processor must be in PROC_LOADED state.
 430  *      This will be an OEM-only function, and not part of the 'Bridge
 431  *      application developer's API.
 432  *  Parameters:
 433  *      hprocessor  :       The processor handle.
 434  *  Returns:
 435  *      0     :       Success.
 436  *      -EFAULT :       Invalid processor handle.
 437  *      -EBADR:    Processor is not in PROC_LOADED state.
 438  *      -EPERM   :       Unable to start the processor.
 439  *  Requires:
 440  *      PROC Initialized.
 441  *  Ensures:
 442  *      Success and ProcState == PROC_RUNNING or DSP_FAILED status.
 443  *  Details:
 444  */
 445 extern int proc_stop(void *hprocessor);
 446
 447 /*
 448  *  ======== proc_end_dma ========
 449  *  Purpose:
 450  *      Begin a DMA transfer
 451  *  Parameters:
 452  *      hprocessor      :   The processor handle.
 453  *      pmpu_addr       :   Buffer start address
 454  *      ul_size         :   Buffer size
 455  *      dir             :   The direction of the transfer
 456  *  Requires:
 457  *      Memory was previously mapped.
 458  */
 459 extern int proc_end_dma(void *hprocessor, void *pmpu_addr, u32 ul_size,
 460                                                 enum dma_data_direction dir);
 461 /*
 462  *  ======== proc_begin_dma ========
 463  *  Purpose:
 464  *      Begin a DMA transfer
 465  *  Parameters:
 466  *      hprocessor      :   The processor handle.
 467  *      pmpu_addr       :   Buffer start address
 468  *      ul_size         :   Buffer size
 469  *      dir             :   The direction of the transfer
 470  *  Requires:
 471  *      Memory was previously mapped.
 472  */
 473 extern int proc_begin_dma(void *hprocessor, void *pmpu_addr, u32 ul_size,
 474                                                 enum dma_data_direction dir);
 475
 476 /*
 477  *  ======== proc_flush_memory ========
 478  *  Purpose:
 479  *      Flushes a buffer from the MPU data cache.
 480  *  Parameters:
 481  *      hprocessor      :   The processor handle.
 482  *      pmpu_addr       :   Buffer start address
 483  *      ul_size   :   Buffer size
 484  *      ul_flags         :   Reserved.
 485  *  Returns:
 486  *      0        :   Success.
 487  *      -EFAULT     :   Invalid processor handle.
 488  *      -EPERM       :   General failure.
 489  *  Requires:
 490  *      PROC Initialized.
 491  *  Ensures:
 492  *  Details:
 493  *      All the arguments are currently ignored.
 494  */
 495 extern int proc_flush_memory(void *hprocessor,
 496                                     void *pmpu_addr, u32 ul_size, u32 ul_flags);
 497
 498 /*
 499  *  ======== proc_invalidate_memory ========
 500  *  Purpose:
 501  *      Invalidates a buffer from the MPU data cache.
 502  *  Parameters:
 503  *      hprocessor      :   The processor handle.
 504  *      pmpu_addr       :   Buffer start address
 505  *      ul_size   :   Buffer size
 506  *  Returns:
 507  *      0        :   Success.
 508  *      -EFAULT     :   Invalid processor handle.
 509  *      -EPERM       :   General failure.
 510  *  Requires:
 511  *      PROC Initialized.
 512  *  Ensures:
 513  *  Details:
 514  *      All the arguments are currently ignored.
 515  */
 516 extern int proc_invalidate_memory(void *hprocessor,
 517                                          void *pmpu_addr, u32 ul_size);
 518
 519 /*
 520  *  ======== proc_map ========
 521  *  Purpose:
 522  *      Maps a MPU buffer to DSP address space.
 523  *  Parameters:
 524  *      hprocessor      :   The processor handle.
 525  *      pmpu_addr       :   Starting address of the memory region to map.
 526  *      ul_size   :   Size of the memory region to map.
 527  *      req_addr        :   Requested DSP start address. Offset-adjusted actual
 528  *                        mapped address is in the last argument.
 529  *      pp_map_addr       :   Ptr to DSP side mapped u8 address.
 530  *      ul_map_attr       :   Optional endianness attributes, virt to phys flag.
 531  *  Returns:
 532  *      0        :   Success.
 533  *      -EFAULT     :   Invalid processor handle.
 534  *      -EPERM       :   General failure.
 535  *      -ENOMEM     :   MPU side memory allocation error.
 536  *      -ENOENT   :   Cannot find a reserved region starting with this
 537  *                    :   address.
 538  *  Requires:
 539  *      pmpu_addr is not NULL
 540  *      ul_size is not zero
 541  *      pp_map_addr is not NULL
 542  *      PROC Initialized.
 543  *  Ensures:
 544  *  Details:
 545  */
 546 extern int proc_map(void *hprocessor,
 547                            void *pmpu_addr,
 548                            u32 ul_size,
 549                            void *req_addr,
 550                            void **pp_map_addr, u32 ul_map_attr,
 551                            struct process_context *pr_ctxt);
 552
 553 /*
 554  *  ======== proc_reserve_memory ========
 555  *  Purpose:
 556  *      Reserve a virtually contiguous region of DSP address space.
 557  *  Parameters:
 558  *      hprocessor      :   The processor handle.
 559  *      ul_size   :   Size of the address space to reserve.
 560  *      pp_rsv_addr       :   Ptr to DSP side reserved u8 address.
 561  *  Returns:
 562  *      0        :   Success.
 563  *      -EFAULT     :   Invalid processor handle.
 564  *      -EPERM       :   General failure.
 565  *      -ENOMEM     :   Cannot reserve chunk of this size.
 566  *  Requires:
 567  *      pp_rsv_addr is not NULL
 568  *      PROC Initialized.
 569  *  Ensures:
 570  *  Details:
 571  */
 572 extern int proc_reserve_memory(void *hprocessor,
 573                                       u32 ul_size, void **pp_rsv_addr,
 574                                       struct process_context *pr_ctxt);
 575
 576 /*
 577  *  ======== proc_un_map ========
 578  *  Purpose:
 579  *      Removes a MPU buffer mapping from the DSP address space.
 580  *  Parameters:
 581  *      hprocessor      :   The processor handle.
 582  *      map_addr        :   Starting address of the mapped memory region.
 583  *  Returns:
 584  *      0        :   Success.
 585  *      -EFAULT     :   Invalid processor handle.
 586  *      -EPERM       :   General failure.
 587  *      -ENOENT   :   Cannot find a mapped region starting with this
 588  *                    :   address.
 589  *  Requires:
 590  *      map_addr is not NULL
 591  *      PROC Initialized.
 592  *  Ensures:
 593  *  Details:
 594  */
 595 extern int proc_un_map(void *hprocessor, void *map_addr,
 596                               struct process_context *pr_ctxt);
 597
 598 /*
 599  *  ======== proc_un_reserve_memory ========
 600  *  Purpose:
 601  *      Frees a previously reserved region of DSP address space.
 602  *  Parameters:
 603  *      hprocessor      :   The processor handle.
 604  *      prsv_addr       :   Ptr to DSP side reservedBYTE address.
 605  *  Returns:
 606  *      0        :   Success.
 607  *      -EFAULT     :   Invalid processor handle.
 608  *      -EPERM       :   General failure.
 609  *      -ENOENT   :   Cannot find a reserved region starting with this
 610  *                    :   address.
 611  *  Requires:
 612  *      prsv_addr is not NULL
 613  *      PROC Initialized.
 614  *  Ensures:
 615  *  Details:
 616  */
 617 extern int proc_un_reserve_memory(void *hprocessor,
 618                                          void *prsv_addr,
 619                                          struct process_context *pr_ctxt);
 620
 621 #endif /* PROC_ */