1 /*---------------------------------------------------------------------------*
2   Project:      Nintendo IO Profiler Shim Library
3   File:         io_prof.h
4   Description:  This file provides the IO Profiler APIs to get
5                 IO utilization per channel.
6 
7   Copyright (C) Nintendo.  All rights reserved.
8 
9   These coded instructions, statements, and computer programs contain
10   proprietary information of Nintendo of America Inc. and/or Nintendo
11   Company Ltd., and are protected by Federal copyright law.  They may
12   not be disclosed to third parties or copied or duplicated in any form,
13   in whole or in part, without the prior written consent of Nintendo.
14 
15   *---------------------------------------------------------------------------*/
16 
17 
18 #ifdef __ghs__
19 #include <types.h>
20 #endif
21 
22 #include <cafe/io_profstat.h>
23 
24 #ifndef IO_PROFAPI_H
25 #define IO_PROFAPI_H
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /*---------------------------------------------------------------------------*
32 
33       Constants defined for this file
34       -- #Defines --
35 
36 -----------------------------------------------------------------------------*/
37 
38 #define IO_PROF_BUFFER_ALIGN (64)
39 
40 /* Return codes */
41 #define IO_PROF_RVAL_OK                                   (0)
42 #define IO_PROF_RVAL_INVALID_ARG                          (-3145728)
43 #define IO_PROF_RVAL_NOT_AVAILABLE                        (-3145729)
44 #define IO_PROF_RVAL_INVALID_STATE                        (-3145730)
45 #define IO_PROF_RVAL_NOTREADY                             (-3145731)
46 
47 /* Profile data request flags */
48 #define IO_PROF_REQUEST_FLAG_RESET_N_RESTART    0x1 /* Reset and restart checkpoint */
49 
50 /*---------------------------------------------------------------------------*
51 
52       Data types defined for this file
53       -- Structs, Typedefs, Enums --
54 
55   ---------------------------------------------------------------------------*/
56 typedef int IO_PROF_RVAL;
57 
58 
59 /*---------------------------------------------------------------------------
60   Name:         IO_ProfilerLibInit()
61 
62   Description:  Initialize IO profiler library
63                 (typically to be called only once by the app).
64 
65   Arguments:    None
66 
67   Returns:      IO_PROF_RVAL_OK on success. Appropriate error code on failure.
68 *---------------------------------------------------------------------------*/
69 IO_PROF_RVAL IO_ProfilerLibInit(void);
70 
71 /*---------------------------------------------------------------------------
72   Name:         IO_ProfilerLibFinish()
73 
74   Description:  Cleanup IO profiler library after application has finished
75                 using it (typically to be called only once by the app).
76 
77   Arguments:    None
78 
79   Returns:      IO_PROF_RVAL_OK on success. Appropriate error code on failure.
80 *---------------------------------------------------------------------------*/
81 IO_PROF_RVAL IO_ProfilerLibFinish(void);
82 
83 /*--------------------------------------------------------------------------*
84    Name:        IO_ProfilerStartCheckpoint
85 
86    Description: Start profiler checkpoint (reset any previous data if any)
87 
88    Arguments:
89          flags: Currently unused, pass 0.
90 
91    Returns:
92          IO_PROF_RVAL_OK on success, appropriate error code otherwise.
93 *--------------------------------------------------------------------------*/
94 IO_PROF_RVAL IO_ProfilerStartCheckpoint(u32 flags);
95 
96 /*--------------------------------------------------------------------------*
97    Name:        IO_ProfilerGetStatsAndEndCheckpoint
98 
99    Description: End profiler checkpoint, get profiling data (from the
100                 previous check point start till now).
101 
102    Arguments:
103          flags: Currently unused, pass 0.
104          duration: Duration (in microseconds) from the previous checkpoint
105                 start till now.
106          stats: Pointer to an array of IO_ProfStat structures in which
107                 the profile data from IO channels is returned. IO_ProfStat
108                 structure is defined in 'cafe/io_profstat.h'. 'stat' buffer
109                 address and size must be IO_PROF_BUFFER_ALIGN aligned.
110          nstats: A pointer holding size of stats array (that is, the number
111                  of IO_ProfStat structures in stats). Upon completion
112                  of the call, it contains how many of the buffers contain
113                  profiling data.
114 
115    Returns:
116          IO_PROF_RVAL_OK on success, appropriate error code otherwise.
117 *--------------------------------------------------------------------------*/
118 IO_PROF_RVAL IO_ProfilerGetStatsAndEndCheckpoint(u32 flags,
119                                  u32 *duration,
120                                  IO_ProfStat* stats,
121                                  int *nstats);
122 
123 /*--------------------------------------------------------------------------*
124    Name:        IO_ProfilerGetStatsAndRestartCheckpoint
125 
126    Description: End profiler checkpoint, get profiling data (from the
127                 previous check point start till now) and start another
128                 profiling checkpoint. This is similar to calling
129                 IO_ProfilerGetStatsAndEndCheckpoint followed immediately by
130                 IO_ProfilerStartCheckpoint
131 
132    Arguments:
133          flags: Currently unused, pass 0.
134          duration: Duration (in microseconds) from the previous checkpoint
135                 start till now.
136          stats: Pointer to an array of IO_ProfStat structures in which
137                 the profile data from IO channels is returned. IO_ProfStat
138                 structure is defined in 'cafe/io_profstat.h'.  'stat' buffer
139                 address and size must be IO_PROF_BUFFER_ALIGN aligned.
140          nstats: A pointer holding size of stats array (that is, the number
141                  of IO_ProfStat structures in stats). Upon completion
142                  of the call, it contains how many of the buffers contain
143                  profiling data.
144 
145    Returns:
146          IO_PROF_RVAL_OK on success, appropriate error code otherwise.
147 *--------------------------------------------------------------------------*/
148 IO_PROF_RVAL IO_ProfilerGetStatsAndRestartCheckpoint(u32 flags,
149                                  u32 *duration,
150                                  IO_ProfStat* stats,
151                                  int *nstats);
152 
153 #ifdef __cplusplus
154 }
155 #endif
156 
157 #endif /* IO_PROFAPI_H */
158