1 /*---------------------------------------------------------------------------*
2 Project: Horizon
3 File: dsp_Api.h
4
5 Copyright (C)2009 Nintendo Co., Ltd. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 $Rev: 25972 $
14 *---------------------------------------------------------------------------*/
15
16 /*! @file
17 @brief DSP ライブラリの初期化、終了を行う API です。
18 */
19 #ifndef NN_DSP_CTR_DSP_API_H_
20 #define NN_DSP_CTR_DSP_API_H_
21
22 #include <nn/Handle.h>
23
24 namespace nn {
25 namespace dsp {
26 namespace CTR {
27
28 namespace detail
29 {
30 nn::Result InitializeBase(Handle* pSession, const char* name);
31 nn::Result FinalizeBase (Handle* pSession);
32 }
33
34 namespace
35 {
36 const char PORT_NAME_DSP[] = "dsp::DSP";
37 }
38
InitializeIpc(Handle * pSession)39 inline nn::Result InitializeIpc(Handle* pSession) { return detail::InitializeBase(pSession, PORT_NAME_DSP); }
FinalizeIpc(Handle * pSession)40 inline nn::Result FinalizeIpc (Handle* pSession) { return detail::FinalizeBase (pSession); }
41
42 /*!
43 @name Initialize/Finalize
44 @{
45 */
46
47 /*!
48 @brief DSP ライブラリの初期化を行い、DSP プロセスとのセッションを確立します。
49 @return 処理の結果が返ります。
50 */
51 nn::Result Initialize( void );
52
53 /*!
54 @brief DSP ライブラリを終了します。
55 @return なし。
56 */
57 void Finalize( void );
58
59 /*!
60 @brief DSP コンポーネントファイルをロードし、DSP を起動します。
61 @param[in] pComponent コンポーネントファイルのアドレス。
62 @param[in] size コンポーネントファイルのサイズ。
63 @param[in] maskPram 使用する DSP-Pram ブロックを指定します。LSB からMSB 方向にブロック0、1、...、7 を表します。8〜15 ビットは無効です。
64 @param[in] maskDram 使用する DSP-Dram ブロックを指定します。maskDram を参照。
65 @return 処理の結果が返ります。
66 */
67 nn::Result LoadComponent( const u8 pComponent[], size_t size, bit16 maskPram = 0xff, bit16 maskDram = 0xff ) ;
68 nn::Result LoadComponentCore( const u8 pComponent[], size_t size, bit16 maskPram = 0xff, bit16 maskDram = 0xff ) ;
69
70 /*!
71 @brief デフォルトの DSP コンポーネントファイル（サウンド）をロードし、DSP を起動します。
72 @return 処理の結果が返ります。
73 */
74 nn::Result LoadDefaultComponent( void );
75
76 /*!
77 @brief DSP を停止します。
78 @return 処理の結果が返ります。
79 */
80 nn::Result UnloadComponent( void );
81 nn::Result UnloadComponentCore( void );
82
83 /*!
84 @}
85 */
86
87 /*!
88 @name CPU-DSP 間通信
89 @{
90 */
91
92 /*!
93 @brief DSP 割り込みを受信するためのイベントハンドルを DSP プロセスに登録します。
94 @param[in] handle イベントオブジェクトのハンドル。
95 @param[in] type 割り込みタイプ。
96 @param[in] port PIPE のポート番号（type が PIPE の場合のみ有効）。
97 @return 処理の結果が返ります。
98 */
99 nn::Result RegisterInterruptEvents(nn::Handle handle, s32 type, s32 port = 0);
100
101 /*!
102 @brief リプライレジスタの値を取得します。
103 @param[in] regNo リプライレジスタ番号。
104 @param[out] pValue 値を格納するアドレス。
105 @return 処理の結果が返ります。
106 */
107 nn::Result RecvData( u16 regNo, u16 *pValue );
108
109 /*!
110 @brief コマンドレジスタに値を設定します。
111 @param[in] regNo コマンドレジスタ番号。
112 @param[in] value 設定する値。
113 @return 処理の結果が返ります。
114 */
115 nn::Result SendData( u16 regNo, u16 value );
116
117 /*!
118 @brief リプライレジスタに値が書き込まれているかどうかを確認します。
119 @param[in] regNo リプライレジスタ番号。
120 @param[out] pStatus 状態を格納するアドレス。
121 @return 処理の結果が返ります。
122 */
123 nn::Result RecvDataIsReady( u16 regNo, bool* pStatus );
124
125 /*!
126 @brief コマンドレジスタが読み込まれたかどうかを確認します。
127 @param[in] regNo コマンドレジスタ番号。
128 @param[out] pStatus 状態を格納するアドレス。
129 @return 処理の結果が返ります。
130 */
131 nn::Result SendDataIsEmpty( u16 regNo, bool * pStatus );
132
133 /*!
134 :private
135 @brief DSP-Wram アドレスおよび連続領域アドレスの仮想アドレスを取得します。
136 @param[in] physicalAddress 物理アドレス。
137 @param[out] pVirtualAddress 仮想アドレスの格納先。
138 @return 処理の結果が返ります。
139 */
140 nn::Result GetVirtualAddress(uptr physicalAddress, uptr * pVirtualAddress);
141
142 /*!
143 :private
144 @brief DSP-Wram アドレスおよび連続領域アドレスの物理アドレスを取得します。
145 @param[in] virtualAddress 仮想アドレス。
146 @param[out] pPhysicalAddress 物理アドレスの格納先。
147 @return 処理の結果が返ります。
148 */
149 nn::Result GetPhysicalAddress(uptr address, uptr * pPhysicalAddress);
150
151 /*!
152 :private
153 @brief DSP 環境におけるアドレスを、CPU 環境におけるアドレスに変換します。
154 @param[in] addressOnDsp DSP 環境におけるアドレス。
155 @param[out] pAddressOnHost CPU 環境におけるアドレスの格納先。
156 @return 処理の結果が返ります。
157 */
158 nn::Result ConvertProcessAddressFromDspDram(uptr addressOnDsp, uptr * pAddressOnHost);
159
160 /*!
161 @brief DSP pipe からデータを読みます。
162 @param[in] port ポート番号。
163 @param[in] buffer データを読み込むバッファのアドレス。
164 @param[in] length 読み込みデータ長。
165 @param[out] pLengthRead 実際に読み込まれたデータ長の格納先。
166 @return 処理の結果が返ります。
167 */
168 nn::Result ReadPipeIfPossible( int port, void* buffer, u16 length, u16* pLengthRead );
169
170 /*!
171 @brief DSP pipe へデータを書きます。
172 @param[in] port ポート番号。
173 @param[in] buffer データを書き込むバッファのアドレス。
174 @param[in] length 書き込みデータ長。
175 @return 処理の結果が返ります。
176 */
177 nn::Result WriteProcessPipe( int port, const void *buffer, u32 length );
178
179 /*!
180 @brief セマフォのリクエストを取得します。
181 @param[in] pIsRequested リクエストの有無。
182 @return 処理の結果が返ります。
183 */
184 nn::Result CheckSemaphoreRequest( bool* pIsRequested );
185
186 /*!
187 @brief セマフォをクリアします。
188 @param[in] mask マスク。
189 @return 処理の結果が返ります。
190 */
191 nn::Result ClearSemaphore( u16 mask );
192
193 /*!
194 @brief セマフォのマスクを設定します。
195 @param[in] mask マスク。
196 @return 処理の結果が返ります。
197 */
198 nn::Result MaskSemaphore( u16 mask );
199
200 /*!
201 @brief セマフォの値を取得します。
202 @param[in] pMask 値の格納先。
203 @return 処理の結果が返ります。
204 */
205 nn::Result GetSemaphore( u16* pMask );
206
207 /*!
208 @brief セマフォの値を設定します。
209 @param[in] mask マスク。
210 @return 処理の結果が返ります。
211 */
212 nn::Result SetSemaphore( u16 mask );
213
214 /*!
215 :private
216 @brief セマフォイベントのハンドルを取得します。
217 @param[out] pHandle 値の格納先。
218 @return 処理の結果が返ります。
219 */
220 nn::Result GetSemaphoreEventHandle ( nn::Handle *);
221
222 /*!
223 :private
224 @brief セマフォイベントで設定するマスクの値を設定します。
225 @param[in] mask 設定するマスクの値。
226 @return 処理の結果が返ります。
227 */
228 nn::Result SetSemaphoreEventMask ( bit16 );
229
230 /*!
231 @}
232 */
233
234 /*!
235 @brief 指定された範囲のデータをキャッシュからメモリに書き戻し、キャッシュを無効にします。
236 @param[in] addr 先頭アドレス。
237 @param[in] size サイズ。
238 @return 処理の結果が返ります。
239 */
240 nn::Result FlushDataCache( uptr addr, size_t size );
241
242 /*!
243 @brief 指定された範囲のキャッシュを無効にします。
244 @param[in] addr 先頭アドレス。
245 @param[in] size サイズ。
246 @return 処理の結果が返ります。
247 */
248 nn::Result InvalidateDataCache( uptr addr, size_t size );
249
250 /*!
251 :private
252 @brief DSP にコンポーネントがロードされているかどうかを確認します。
253 @return ロードされていれば true を、されていなければ false を返します。
254 */
255 bool IsComponentLoaded(void);
256
257 /*!
258 @brief DSP で行っている処理を一時中断し、終了処理を行います。
259 @return 実際にスリープ処理が行われば場合は true を、何もしなかった場合は false を返します。
260 */
261 bool Sleep(void);
262
263 /*!
264 @brief 一時中断した DSP の処理を復元します。
265 @brief なし。
266 */
267 void WakeUp(void);
268
269 /*! :private
270 @brief 終了処理のための準備を行います。
271 */
272 void OrderToWaitForFinalize();
273
274 /*! :private
275 @brief Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを設定します。
276 @param[in] sleepCallback Sleep 時のコールバック
277 @param[in] wakeUpCallback WakeUp 時のコールバック
278 @param[in] orderToWaitForFinalizeCallback OrderToWaitForFinalize 時のコールバック
279 @return コールバックの設定に成功したら true を、失敗したら false を返します。
280 */
281 bool RegisterSleepWakeUpCallback(
282 void (*sleepCallback)(),
283 void (*wakeUpCallback)(),
284 void (*orderToWaitForFinalizeCallback)() = NULL
285 );
286
287 /*! :private
288 @brief Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを無効にします。
289 @param[in] sleepCallback Sleep 時のコールバック
290 @param[in] wakeUpCallback WakeUp 時のコールバック
291 @param[in] orderToWaitForFinalizeCallback OrderToWaitForFinalize 時のコールバック
292 @return コールバックの無効化に成功したら true を、失敗したら false を返します。
293 */
294 bool ClearSleepWakeUpCallback(
295 void (*sleepCallback)(),
296 void (*wakeUpCallback)(),
297 void (*orderToWaitForFinalizeCallback)() = NULL
298 );
299
300 /*!
301 @brief ヘッドホンの挿入状態を取得します。
302 @param[out] isConnected 挿入されていれば true が返ってきます。
303 @return 処理の結果が返ります。
304 */
305 nn::Result GetHeadphoneStatus(bool* isConnected);
306
307 /*!
308 :private
309 @brief DSP が占有状態を取得します。
310 @return 占有されていれば true を、そうでなければ false を返します。
311 */
312 bool IsDspOccupied(void);
313
314 } // namespace CTR {
315 } // namespace dsp {
316 } // namespace nn {
317
318 #endif // ifndef NN_DSP_CTR_DSP_API_H_
319