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