sys/dev/pci/n8/include_private/n8_driver_api.h

   1 /*-
   2  * Copyright (C) 2001-2003 by NBMK Encryption Technologies.
   3  * All rights reserved.
   4  *
   5  * NBMK Encryption Technologies provides no support of any kind for
   6  * this software.  Questions or concerns about it may be addressed to
   7  * the members of the relevant open-source community at
   8  * <tech-crypto@netbsd.org>.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are
  12  * met:
  13  *
  14  * 1. Redistributions of source code must retain the above copyright
  15  *    notice, this list of conditions and the following disclaimer.
  16  *
  17  * 2. Redistributions in binary form must reproduce the above
  18  *    copyright notice, this list of conditions and the following
  19  *    disclaimer in the documentation and/or other materials provided
  20  *    with the distribution.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 /*****************************************************************************
  36  * @(#) n8_driver_api.h 1.11@(#)
  37  *****************************************************************************/
  38
  39 /*****************************************************************************/
  40 /** @file n8_driver_api.h
  41  *  @brief NSP2000 Driver API - Prototypes and Resources.
  42  *
  43  * This header contains prototypes for using the NSP2000 driver API, as well
  44  * as data structures and other resources. This header must be included
  45  * by any application wishing to make driver API calls.
  46  *****************************************************************************/
  47
  48 /*****************************************************************************
  49  * Revision history:
  50  * 04/21/03 brr   Added support for multiple memory banks.
  51  * 04/01/03 brr   Reverted N8_WaitOnRequest to accept timeout parameter.
  52  * 03/19/03 brr   Modified prototype for N8_WaitOnRequest to accept an API
  53  *                request pointer.
  54  * 10/25/02 brr   Clean up function prototypes & include files.
  55  * 10/22/02 brr   Added openMode parameter to N8_OpenDevice.
  56  * 10/11/02 brr   Added timeout parameter to N8_WaitOnRequest.
  57  * 09/18/02 brr   Added prototypes for N8_DiagInfo & N8_WaitOnRequest.
  58  * 07/19/02 brr   Moved definitions of N8_VirtToPhys & N8_PhysToVirt from here
  59  *                to n8_OS_intf.h.
  60  * 07/17/02 brr   Update comments & eliminate unused prototypes.
  61  * 07/02/02 brr   Added prototype for N8_QueryMemStatistics & N8_QMgrDequeue.
  62  * 03/29/02 hml   Added proto for N8_ContextMemValidate.
  63  * 03/27/02 hml   Changed N8_QueueReturnCodees_t to N8_Status_t.
  64  * 03/26/02 hml   Updated protos for N8_ContextMemFree and N8_ContextMemAlloc.
  65  * 03/22/02 hml   Removed sessionID from the N8_ContextMemAlloc proto.
  66  * 03/21/02 mmd   Implemented N8_QMgrQueryStatistics.
  67  * 03/18/02 brr   Added Context Memory API calls.
  68  * 03/01/02 brr   Do not include driver include files.
  69  * 02/25/02 brr   Reworked function prototypes for 2.1 changes & removed
  70  *                obsolete IOCTL's.
  71  * 02/01/02 brr   Fixed include files.
  72  * 01/31/02 brr   Modified memory management functions to improve performance.
  73  * 11/10/01 brr   Modified to support static allocations of persistant data
  74  *                by the driver.
  75  * 10/22/01 mmd   Added new 3rd parm to N8_InitializeFPGA.
  76  * 10/15/01 mmd   Implemented N8_DriverDebug.
  77  * 10/12/01 dkm   Moved public portion to n8_pub_common.h.
  78  * 10/02/01 mmd   N8_InitializeFPGA now returns N8_EVENT_INCOMPLETE if the
  79  *                FPGA is currently being programmed by another entity.
  80  * 09/25/01 mmd   Implemented N8_GetConfigurationItem.
  81  * 09/05/01 bac   Renamed formal parameter FPGA in N8_IsFPGA to avoid
  82  *                compilation problems with the define of the same name.
  83  * 08/28/01 mmd   Revised API to new version.
  84  * 08/28/01 mmd   Added Key and Bitfield fields to N8_MemoryHandle_t, and now
  85  *                including memorycategories.h.
  86  * 08/16/01 mmd   Eliminated "simon", renamed, and revised to include the
  87  *                NSP2000 register layout for application use.
  88  * 07/25/01 mmd   Added N8_IsFPGA.
  89  * 06/28/01 jke   Fixed Makefile such that include of n8_errors.h not need
  90  *                explicit path info
  91  * 06/05/01 mmd   Corrected N8_TestBuffer according to API spec.
  92  * 05/29/01 mmd   Incorporated suggestions from code review.
  93  * 05/17/01 mmd   Original version.
  94  ****************************************************************************/
  95 /** @defgroup nsp2000drv NSP2000 Driver API - Prototypes and Resources.
  96  */
  97
  98 #ifndef N8_DRIVER_API_H
  99 #define N8_DRIVER_API_H
 100
 101 #include "n8_pub_common.h"
 102 #include "n8_pub_errors.h"
 103 #include "n8_pub_rng.h"
 104 #include "n8_malloc_common.h"
 105 #include "n8_enqueue_common.h"
 106 #include "n8_device_info.h"
 107 #include "nsp_ioctl.h"
 108
 109
 110
 111 /*****************************************************************************
 112  * N8_OpenDevice
 113  *****************************************************************************/
 114 /** @ingroup NSP2000_Driver_API
 115  * @brief Opens and initializes the NSP2000 driver.
 116  *
 117  * This routine opens the driver, and sets up all resources required to use
 118  * the NSP2000.
 119  *
 120  * @param driverInfo_p   RO: Pointer to structure that holds information
 121  *                           describing the driver's resources.
 122  * @param allocUserPool  RO: Flag indicating whether the process opening this
 123  *                           device needs memory resources mmap'ed to user space
 124  * @param openMode       RO: Flag indicating whether the process opening this
 125  *                           device intends to run diagnostics.
 126  *
 127  *
 128  * @par Externals:
 129  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands. <BR>
 130  *    N8_*          RO: #define - Return codes from NetOctave API.
 131  *
 132  * @return
 133  *    N8_STATUS_OK                Success.
 134  *    N8_INVALID_OBJECT           Failed - invalid devnode, or NULL nspregs
 135  *                                pointer, or driver not loaded, or invalid
 136  *                                hardware instance.
 137  *    N8_UNEXPECTED_ERROR         Failed - the MMAP call failed (*highly* unlikely).
 138  *    N8_INVALID_DRIVER_VERSION   Failed - the driver installed is incompatible.
 139  *
 140  * @par Errors:
 141  *    See return section for error information.
 142  *****************************************************************************/
 143
 144 extern N8_Status_t N8_OpenDevice(NSPdriverInfo_t *driverInfo_p,
 145                                  N8_Boolean_t     allocUserPool,
 146                                  N8_Open_t        openMode);
 147
 148
 149
 150 /*****************************************************************************
 151  * N8_AllocateBuffer
 152  *****************************************************************************/
 153 /** @ingroup NSP2000_Driver_API
 154  * @brief Allocates a buffer and maps it between user and kernel space.
 155  *
 156  * This routine follows two steps. It first requests that the driver allocate
 157  * memory with characteristics dictated by the caller.
 158  *
 159  * For more information on this call, please refer to the NSP2000 Device
 160  * Driver Specification Document.
 161  *
 162  * The N8_MemoryHandle_t should be treated as read-only upon return from this
 163  * call, for subsequent calls to N8_TestBuffer and N8_FreeBuffer.
 164  *
 165  * @parm
 166  *         size           R0: Size of allocation request in bytes.
 167  *
 168  * @return MemoryStruct*  RW: Pointer to a struct that associates the necessary
 169  *                            parameters that completely identify an allocated
 170  *                            buffer. NULL if allocation fails
 171  *
 172  * @par Externals:
 173  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands.     <BR>
 174  *
 175  * @par Errors:
 176  *    See return section for error information.
 177  *****************************************************************************/
 178
 179 extern N8_MemoryHandle_t * N8_AllocateBuffer(const unsigned int size);
 180 extern N8_MemoryHandle_t * N8_AllocateBufferPK(const unsigned int size);
 181
 182
 183
 184 /*****************************************************************************
 185  * N8_FreeBuffer
 186  *****************************************************************************/
 187 /** @ingroup NSP2000_Driver_API
 188  * @brief Frees buffers allocated with N8_AllocateBuffer.
 189  *
 190  * It requests that the driver free the buffer.
 191  *
 192  * @param MemoryStruct   RO: Pointer to a struct that associates the necessary
 193  *                           parameters that completely identify an allocated
 194  *                           buffer.
 195  *
 196  * @par Externals:
 197  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands.
 198  *
 199  * @return
 200  *    N/A
 201  *
 202  * @par Errors:
 203  *    See return section for error information.
 204  *****************************************************************************/
 205
 206 extern void N8_FreeBuffer(N8_MemoryHandle_t *MemoryStruct);
 207
 208
 209 /*****************************************************************************
 210  * N8_CloseDevice
 211  *****************************************************************************/
 212 /** @ingroup NSP2000_Driver_API
 213  * @brief Closes the NSP2000 device driver.
 214  *
 215  * This routine closes the NSP2000 driver, and is intended to be called just
 216  * before an application terminates.
 217  *
 218  * @return
 219  *    N/A
 220  *
 221  * @par Errors:
 222  *    See return section for error information.
 223  *****************************************************************************/
 224
 225 extern void N8_CloseDevice(void);
 226
 227
 228 /*****************************************************************************
 229  * N8_WaitOnInterrupt
 230  *****************************************************************************/
 231 /** @ingroup NSP2000_Driver_API
 232  * @brief Block for an interrupt from the NSP2000 device driver.
 233  *
 234  * This routine blocks until the NSP2000 device driver reports receipt of an
 235  * interrupt from the specified execution core, or until the timeout value is
 236  * reached. Must use a real handle.
 237  *
 238  * @param chip        RO: Chip number of chip we are waiting on.
 239  * @param coretype    RO: Selects which execution core to monitor. Must be
 240  *                        set to N8_DAPI_PKE, N8_DAPI_RNG, or N8_DAPI_EA.
 241  * @param bitmask     RO: Bitmask to be applied to interrupt register, to
 242  *                        select which interrupts will trigger a return.
 243  * @param timeout     RO: Timeout value, in seconds.
 244  *
 245  * @par Externals:
 246  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands.  <BR>
 247  *    N8_*          RO: #define - Return codes from NetOctave API.
 248  *
 249  * @return
 250  *    N8_STATUS_OK            Received at least one of the specified IRQs.
 251  *    N8_INVALID_PARAMETER    Invalid coretype.
 252  *    N8_EVENT_INCOMPLETE     Request timed out - IRQ not received.
 253  *
 254  * @par Errors:
 255  *    See return section for error information.
 256  *****************************************************************************/
 257
 258 extern N8_Status_t N8_WaitOnInterrupt( N8_Unit_t      chip,
 259                                        unsigned char  coretype,
 260                                        unsigned long  bitmask,
 261                                        unsigned long  timeout );
 262
 263
 264
 265 /*****************************************************************************
 266  * N8_QMgrQueryStatistics
 267  *****************************************************************************/
 268 /** @ingroup NSP2000_Driver_API
 269  * @brief Query the QMgr for its current statistics.
 270  *
 271  * This routine queries the driver for Queue Manager performance
 272  * statistics.
 273  *
 274  * @param stats     RW: Returns assorted Queue Manager stat counters. Also
 275  *                      selects which chip's queue to query via the chip
 276  *                      field.
 277  *
 278  * @par Externals:
 279  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands.  <BR>
 280  *    N8_*          RO: #define - Return codes from NetOctave API.
 281  *
 282  * @return
 283  *    N8_STATUS_OK            Success
 284  *    N8_INVALID_PARAMETER    Invalid chip selector.
 285  *
 286  * @par Errors:
 287  *    See return section for error information.
 288  *****************************************************************************/
 289
 290 extern N8_Status_t N8_QMgrQueryStatistics( N8_QueueStatistics_t *stats );
 291
 292 /*****************************************************************************
 293  * N8_DriverDebug
 294  *****************************************************************************/
 295 /** @ingroup NSP2000_Driver_API
 296  * @brief Enables/disables driver debugging messages.
 297  *
 298  * This routine enables/disables debug messages in the driver, and/or displays
 299  * various resource usage info.
 300  *
 301  * @param Selector RO: Selects the debug message family.
 302  *
 303  * @par Externals:
 304  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands. <BR>
 305  *    NSP_DBG_*     RO: #define - Message family selector.         <BR>
 306  *    N8_*          RO: #define - Return codes from NetOctave API.
 307  *
 308  * @return
 309  *    N8_INVALID_PARAMETER   Used invalid message family selector.
 310  *    N8_STATUS_OK           Success.
 311  *
 312  * @par Errors:
 313  *    See return section for error information.
 314  *****************************************************************************/
 315
 316 N8_Status_t N8_DriverDebug(unsigned char Selector);
 317
 318 /*****************************************************************************
 319  * N8_QueryMemStatistics
 320  *****************************************************************************/
 321 /** @ingroup NSP2000_Driver_API
 322  * @brief Query the driver for its memory statistics.
 323  *
 324  * This routine queries the driver for its memory statistics.
 325  *
 326  * @param stats     RW: Returns statistics for the drivers memory pool.
 327  *
 328  * @par Externals:
 329  *    NSP_IOCTL_*   RO: #define - IOCTL codes for driver commands.  <BR>
 330  *    N8_*          RO: #define - Return codes from NetOctave API.
 331  *
 332  * @return
 333  *    N8_STATUS_OK            Success
 334  *    N8_INVALID_PARAMETER    Invalid chip selector.
 335  *    N8_INVALID_OBJECT       Failed - invalid devnode or missing driver.
 336  *
 337  * @par Errors:
 338  *    See return section for error information.
 339  *****************************************************************************/
 340
 341 extern N8_Status_t N8_QueryMemStatistics( MemStats_t *stats );
 342
 343
 344 /*****************************************************************************
 345  * N8_GetFD
 346  *****************************************************************************/
 347 /** @ingroup NSP2000_Driver_API
 348  * @brief Return the file descriptor for the NSP2000.
 349  *
 350  * This routine returns the file descriptor for the NSP2000.
 351  *
 352  * @param
 353  *
 354  * @par Externals:
 355  *    nspDeviceHandle_g   RO: global file descriptor for the NSP2000.
 356  *
 357  * @return
 358  *   int - The NSP2000's file descriptor.
 359  *
 360  * @par Errors:
 361  *****************************************************************************/
 362
 363 extern int N8_GetFD(void);
 364
 365
 366 /*****************************************************************************
 367  * N8_ContextMemAlloc
 368  *****************************************************************************/
 369 /** @ingroup NSP2000Driver
 370  * @brief Allocate an entry from the context memory.
 371  *
 372  * This routine allocates and entry from the context memory on an NPS2000.
 373  *
 374  * @param chip            RO: The chip.
 375  *        index           RW: Pointer to index of the allocated entry.
 376  *
 377  * @return
 378  *    Returns the index of the context memory allocation.
 379  *    -1 - The allocation has failed.
 380  *
 381  * @par Errors:
 382  *    See return section for error information.
 383  *****************************************************************************/
 384
 385 extern N8_Status_t N8_ContextMemAlloc (N8_Unit_t *chip, unsigned int *index_p);
 386
 387 /*****************************************************************************
 388  * N8_ContextMemFree
 389  *****************************************************************************/
 390 /** @ingroup NSP2000Driver
 391  * @brief Free a context memory entry.
 392  *
 393  * This routine frees a context memory entry on an NPS2000.
 394  *
 395  * @param chip            RO: The chip.
 396  *        entry           R0: The index of the entry to be freed.
 397  *
 398  * @return
 399  *
 400  *****************************************************************************/
 401
 402 extern N8_Status_t N8_ContextMemFree  (N8_Unit_t chip, unsigned long entry);
 403
 404 /*****************************************************************************
 405  * N8_ContextMemValidate
 406  *****************************************************************************/
 407 /** @ingroup NSP2000Driver
 408  * @brief Validate a context memory entry.
 409  *
 410  * This routine validates a context memory entry on an NPS2000.
 411  *
 412  * @param chip            RO: The chip.
 413  *        index           R0: The index of the entry to be validated.
 414  *
 415  * @return
 416  *
 417  *****************************************************************************/
 418
 419 extern N8_Status_t N8_ContextMemValidate (N8_Unit_t chip, unsigned int index);
 420
 421 /*****************************************************************************
 422  * N8_QMgrQueue
 423  *****************************************************************************/
 424 /** @ingroup NSP2000Driver
 425  * @brief Queue an API request to the QMgr.
 426  *
 427  * This routine Queues an API request to the QMgr.
 428  *
 429  * @param API_req_p   RO: Pointer to the request to be queued.
 430  *
 431  * @par Externals:
 432  *    nspDeviceHandle_g      RO: File descriptor for the NSP2000
 433  *
 434  * @return
 435  *
 436  *****************************************************************************/
 437
 438 extern N8_Status_t N8_QMgrQueue( API_Request_t *API_req_p );
 439
 440
 441 /*****************************************************************************
 442  * Queue_RN_request
 443  *****************************************************************************/
 444 /** @ingroup NSP2000Driver
 445  * @brief Queue a random number request.
 446  *
 447  * @param RN_req_p        RO: Pointer to the information structure for a
 448  *                            random number request.
 449  *
 450  * @par Externals:
 451  *    nspDeviceHandle_g      RO: File descriptor for the NSP2000
 452  *
 453  * @return
 454  *
 455  *****************************************************************************/
 456
 457 extern N8_Status_t Queue_RN_request( RN_Request_t *rn_req_p );
 458
 459 /*****************************************************************************
 460  * RN_SetParameters
 461  *****************************************************************************/
 462 /** @ingroup NSP2000Driver
 463  * @brief Set random number parameters
 464  *
 465  * @param parms_p         RO: Pointer to the information structure holding
 466  *                            parameters.
 467  *        chip            R0: The chip to set the parameters on.
 468  *
 469  * @par Externals:
 470  *    nspDeviceHandle_g   RO: File descriptor for the NSP2000
 471  *
 472  * @return
 473  *
 474  *****************************************************************************/
 475
 476 extern N8_Status_t RN_SetParameters(N8_RNG_Parameter_t *parms_p, int chip);
 477
 478 /*****************************************************************************
 479  * RN_GetParameters
 480  *****************************************************************************/
 481 /** @ingroup NSP2000Driver
 482  * @brief Get random number parameters
 483  *
 484  * @param parms_p         RO: Pointer to the information structure holding
 485  *                            parameters.
 486  *        chip            R0: The chip to get the parameters on.
 487  *
 488  * @par Externals:
 489  *    nspDeviceHandle_g   RO: File descriptor for the NSP2000
 490  *
 491  * @return
 492  *
 493  *****************************************************************************/
 494
 495 extern N8_Status_t RN_GetParameters(N8_RNG_Parameter_t *parms_p, int chip);
 496
 497 /*****************************************************************************
 498  * N8_QMgrDequeue
 499  *****************************************************************************/
 500 /** @ingroup NSP2000Driver
 501  * @brief Inform the driver a request has been processed
 502  *
 503  * This routine informs the driver a request has been processed
 504  *
 505  * @param
 506  *
 507  * @par Externals:
 508  *    nspDeviceHandle_g      RO: File descriptor for the NSP2000
 509  *
 510  * @return
 511  *
 512  *****************************************************************************/
 513
 514 extern N8_Status_t N8_QMgrDequeue(void);
 515
 516 extern N8_Status_t N8_DiagInfo(int chip, int *regAddr_p, int *eaQueAddr_p,
 517                                int *pkQueAddr_p, int *rnQueAddr_p);
 518 extern N8_Status_t N8_WaitOnRequest(int timeout);
 519
 520 #endif   /* N8_DRIVER_API_H */
 521
 522