/*---------------------------------------------------------------------------*
  Project:      Nintendo IO Profiler Shim Library
  File:         io_prof.h
  Description:  This file provides the IO Profiler APIs to get
                IO utilization per channel.

  Copyright (C) 2012 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  *---------------------------------------------------------------------------*/


#ifdef __ghs__
#include <types.h>
#endif

#include <cafe/io_profstat.h>

#ifndef IO_PROFAPI_H
#define IO_PROFAPI_H

#ifdef __cplusplus
extern "C" {
#endif

/*---------------------------------------------------------------------------*
  
      Constants defined for this file
      -- #Defines --
  
-----------------------------------------------------------------------------*/

#define IO_PROF_BUFFER_ALIGN (64)

/* Return codes */
#define IO_PROF_RVAL_OK                                   (0)
#define IO_PROF_RVAL_INVALID_ARG                          (-3145728)
#define IO_PROF_RVAL_NOT_AVAILABLE                        (-3145729)
#define IO_PROF_RVAL_INVALID_STATE                        (-3145730)
#define IO_PROF_RVAL_NOTREADY                             (-3145731)

/* Profile data request flags */
#define IO_PROF_REQUEST_FLAG_RESET_N_RESTART    0x1 /* Reset and restart checkpoint */

/*---------------------------------------------------------------------------*
  
      Data types defined for this file
      -- Structs, Typedefs, Enums --
  
  ---------------------------------------------------------------------------*/
typedef int IO_PROF_RVAL;


/*---------------------------------------------------------------------------
  Name:         IO_ProfilerLibInit()
  
  Description:  Initialize IO profiler library 
                (typically to be called only once by the app).
  
  Arguments:    None

  Returns:      IO_PROF_RVAL_OK on success. Appropriate error code on failure.
*---------------------------------------------------------------------------*/
IO_PROF_RVAL IO_ProfilerLibInit(void);

/*---------------------------------------------------------------------------
  Name:         IO_ProfilerLibFinish()
  
  Description:  Cleanup IO profiler library after application has finished
                using it (typically to be called only once by the app).
  
  Arguments:    None

  Returns:      IO_PROF_RVAL_OK on success. Appropriate error code on failure.
*---------------------------------------------------------------------------*/
IO_PROF_RVAL IO_ProfilerLibFinish(void);

/*--------------------------------------------------------------------------*
   Name:        IO_ProfilerStartCheckpoint
  
   Description: Start profiler checkpoint (reset any previous data if any) 
  
   Arguments:
         flags: Currently unused, pass 0.
 
   Returns:
         IO_PROF_RVAL_OK on success, appropriate error code otherwise.
*--------------------------------------------------------------------------*/
IO_PROF_RVAL IO_ProfilerStartCheckpoint(u32 flags);

/*--------------------------------------------------------------------------*
   Name:        IO_ProfilerGetStatsAndEndCheckpoint
  
   Description: End profiler checkpoint, get profiling data (from the
                previous check point start till now).
  
   Arguments:
         flags: Currently unused, pass 0.
         duration: Duration (in microseconds) from the previous checkpoint
                start till now.
         stats: Pointer to an array of IO_ProfStat structures in which
                the profile data from IO channels is returned. IO_ProfStat
                structure is defined in 'cafe/io_profstat.h'. 'stat' buffer
                address and size must be IO_PROF_BUFFER_ALIGN aligned.
         nstats: A pointer holding size of stats array (i.e. number
                 of IO_ProfStat structures in stats). Up on completion
                 of the call, it contains how many of the buffers contain
                 profiling data.

   Returns:
         IO_PROF_RVAL_OK on success, appropriate error code otherwise.
*--------------------------------------------------------------------------*/
IO_PROF_RVAL IO_ProfilerGetStatsAndEndCheckpoint(u32 flags,
                                 u32 *duration,
                                 IO_ProfStat* stats,
                                 int *nstats);

/*--------------------------------------------------------------------------*
   Name:        IO_ProfilerGetStatsAndRestartCheckpoint
  
   Description: End profiler checkpoint, get profiling data (from the
                previous check point start till now) and start another
                profiling checkpoint. This is similar to calling
                IO_ProfilerGetStatsAndEndCheckpoint followed immediately by
                IO_ProfilerStartCheckpoint
  
   Arguments:
         flags: Currently unused, pass 0.
         duration: Duration (in microseconds) from the previous checkpoint
                start till now.
         stats: Pointer to an array of IO_ProfStat structures in which
                the profile data from IO channels is returned. IO_ProfStat
                structure is defined in 'cafe/io_profstat.h'.  'stat' buffer
                address and size must be IO_PROF_BUFFER_ALIGN aligned.
         nstats: A pointer holding size of stats array (i.e. number
                 of IO_ProfStat structures in stats). Up on completion
                 of the call, it contains how many of the buffers contain
                 profiling data.

   Returns:
         IO_PROF_RVAL_OK on success, appropriate error code otherwise.
*--------------------------------------------------------------------------*/
IO_PROF_RVAL IO_ProfilerGetStatsAndRestartCheckpoint(u32 flags,
                                 u32 *duration,
                                 IO_ProfStat* stats,
                                 int *nstats);

#ifdef __cplusplus
}
#endif

#endif /* IO_PROFAPI_H */