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: 29251 $
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 /*! :private
134 @brief DSP-Wram アドレスおよび連続領域アドレスの仮想アドレスを取得します。
135 @param[in] physicalAddress 物理アドレス。
136 @param[out] pVirtualAddress 仮想アドレスの格納先。
137 @return 処理の結果が返ります。
138 */
139 nn::Result GetVirtualAddress(uptr physicalAddress, uptr * pVirtualAddress);
140
141 /*! :private
142 @brief DSP-Wram アドレスおよび連続領域アドレスの物理アドレスを取得します。
143 @param[in] virtualAddress 仮想アドレス。
144 @param[out] pPhysicalAddress 物理アドレスの格納先。
145 @return 処理の結果が返ります。
146 */
147 nn::Result GetPhysicalAddress(uptr address, uptr * pPhysicalAddress);
148
149 /*! :private
150 @brief DSP 環境におけるアドレスを、CPU 環境におけるアドレスに変換します。
151 @param[in] addressOnDsp DSP 環境におけるアドレス。
152 @param[out] pAddressOnHost CPU 環境におけるアドレスの格納先。
153 @return 処理の結果が返ります。
154 */
155 nn::Result ConvertProcessAddressFromDspDram(uptr addressOnDsp, uptr * pAddressOnHost);
156
157 /*!
158 @brief DSP pipe からデータを読みます。
159 @param[in] port ポート番号。
160 @param[in] buffer データを読み込むバッファのアドレス。
161 @param[in] length 読み込みデータ長。
162 @param[out] pLengthRead 実際に読み込まれたデータ長の格納先。
163 @return 処理の結果が返ります。
164 */
165 nn::Result ReadPipeIfPossible( int port, void* buffer, u16 length, u16* pLengthRead );
166
167 /*!
168 @brief DSP pipe へデータを書きます。
169 @param[in] port ポート番号。
170 @param[in] buffer データを書き込むバッファのアドレス。
171 @param[in] length 書き込みデータ長。
172 @return 処理の結果が返ります。
173 */
174 nn::Result WriteProcessPipe( int port, const void *buffer, u32 length );
175
176 /*!
177 @brief セマフォのリクエストを取得します。
178 @param[in] pIsRequested リクエストの有無。
179 @return 処理の結果が返ります。
180 */
181 nn::Result CheckSemaphoreRequest( bool* pIsRequested );
182
183 /*!
184 @brief セマフォをクリアします。
185 @param[in] mask マスク。
186 @return 処理の結果が返ります。
187 */
188 nn::Result ClearSemaphore( u16 mask );
189
190 /*!
191 @brief セマフォのマスクを設定します。
192 @param[in] mask マスク。
193 @return 処理の結果が返ります。
194 */
195 nn::Result MaskSemaphore( u16 mask );
196
197 /*!
198 @brief セマフォの値を取得します。
199 @param[in] pMask 値の格納先。
200 @return 処理の結果が返ります。
201 */
202 nn::Result GetSemaphore( u16* pMask );
203
204 /*!
205 @brief セマフォの値を設定します。
206 @param[in] mask マスク。
207 @return 処理の結果が返ります。
208 */
209 nn::Result SetSemaphore( u16 mask );
210
211 /*!
212 :private
213 @brief セマフォイベントのハンドルを取得します。
214 @param[out] pHandle 値の格納先。
215 @return 処理の結果が返ります。
216 */
217 nn::Result GetSemaphoreEventHandle ( nn::Handle *);
218
219 /*!
220 :private
221 @brief セマフォイベントで設定するマスクの値を設定します。
222 @param[in] mask 設定するマスクの値。
223 @return 処理の結果が返ります。
224 */
225 nn::Result SetSemaphoreEventMask ( bit16 );
226
227 /*!
228 @}
229 */
230
231 /*!
232 @brief 指定された範囲のデータをキャッシュからメモリに書き戻し、キャッシュを無効にします。
233 @param[in] addr 先頭アドレス。
234 @param[in] size サイズ。
235 @return 処理の結果が返ります。
236 */
237 nn::Result FlushDataCache( uptr addr, size_t size );
238
239 /*! :private
240 @brief 指定された範囲のキャッシュを無効にします。
241 @param[in] addr 先頭アドレス。
242 @param[in] size サイズ。
243 @return 処理の結果が返ります。
244 */
245 nn::Result InvalidateDataCache( uptr addr, size_t size );
246
247 /*! :private
248 @brief DSP にコンポーネントがロードされているかどうかを確認します。
249 @return ロードされていれば true を、されていなければ false を返します。
250 */
251 bool IsComponentLoaded(void);
252
253 /*!
254 @brief DSP で行っている処理を一時中断し、終了処理を行います。
255 @return 実際にスリープ処理が行われば場合は true を、何もしなかった場合は false を返します。
256 */
257 bool Sleep(void);
258
259 /*!
260 @brief 一時中断した DSP の処理を復元します。
261 @brief なし。
262 */
263 void WakeUp(void);
264
265 /*! :private
266 @brief システムのスリープから復帰します。
267 */
268 void Awake();
269
270 /*! :private
271 @brief 終了処理のための準備を行います。
272 */
273 void OrderToWaitForFinalize();
274
275 /*! :private
276 @brief Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを設定します。
277 @param[in] sleepCallback Sleep 時のコールバック
278 @param[in] wakeUpCallback WakeUp 時のコールバック
279 @param[in] orderToWaitForFinalizeCallback OrderToWaitForFinalize 時のコールバック
280 @return コールバックの設定に成功したら true を、失敗したら false を返します。
281 */
282 bool RegisterSleepWakeUpCallback(
283 void (*sleepCallback)(),
284 void (*wakeUpCallback)(),
285 void (*orderToWaitForFinalizeCallback)() = NULL
286 );
287
288 /*! :private
289 @brief Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを無効にします。
290 @param[in] sleepCallback Sleep 時のコールバック
291 @param[in] wakeUpCallback WakeUp 時のコールバック
292 @param[in] orderToWaitForFinalizeCallback OrderToWaitForFinalize 時のコールバック
293 @return コールバックの無効化に成功したら true を、失敗したら false を返します。
294 */
295 bool ClearSleepWakeUpCallback(
296 void (*sleepCallback)(),
297 void (*wakeUpCallback)(),
298 void (*orderToWaitForFinalizeCallback)() = NULL
299 );
300
301 /*!
302 @brief ヘッドホンの挿入状態を取得します。
303 @param[out] isConnected 挿入されていれば true が返ってきます。
304 @return 処理の結果が返ります。
305 */
306 nn::Result GetHeadphoneStatus(bool* isConnected);
307
308 /*! :private
309 @brief 蓋閉じ時に強制的にヘッドフォン出力にするかどうかを設定します。
310 @param[in] forceout true なら強制ヘッドフォン出力とします。
311 @return 処理の結果が返ります。
312 */
313 Result ForceHeadphoneOut(bool forceout);
314
315 /*!
316 :private
317 @brief DSP が占有状態を取得します。
318 @return 占有されていれば true を、そうでなければ false を返します。
319 */
320 bool IsDspOccupied(void);
321
322 } // namespace CTR {
323 } // namespace dsp {
324 } // namespace nn {
325
326 #endif // ifndef NN_DSP_CTR_DSP_API_H_
327