1 /*---------------------------------------------------------------------------* 2 Project: Revolution OS - DSP Driver and API 3 File: dsp.h 4 5 Copyright (C)1999-2006 Nintendo 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 $Log: dsp.h,v $ 14 Revision 1.4 03/20/2006 11:22:57 hiratsu 15 Fixed unsafe macro. 16 17 Revision 1.3 02/09/2006 04:46:42 aka 18 Changed copyright. 19 20 Revision 1.2 2006/02/04 11:56:44 hashida 21 (none) 22 23 Revision 1.1.1.1 2005/12/29 06:53:27 hiratsu 24 Initial import. 25 26 Revision 1.1.1.1 2005/05/12 02:41:06 yasuh-to 27 Imported from Dolphin tree. 28 29 10 4/28/01 9:14p Eugene 30 Added volatile keyword to state variables in DSPTaskInfo structure, for 31 safety. 32 33 9 4/28/01 7:24p Eugene 34 Added: 35 - DSPAssertTask() 36 - DSPCheckInit() 37 - DSP version/timestamp for debug builds 38 - Some debugging APIs 39 - Priority-based task sorting. 40 41 8 4/26/01 9:57p Eugene 42 Interim check-in for DSP task switching. 43 ================ 44 1. Added "NOYIELD" CPU-to-DSP directive for task resumption without 45 "RESUME" interrupt from DSP. This is an optimization to reduce the 46 number of DSP interrupts in general. 47 2. Added "DSPAssertTask()" so that a higher-priority task can bully a 48 lower-priority task into yielding the DSP. 49 50 7 4/15/01 1:59a Eugene 51 Support for task switching. 52 53 5 3/26/01 9:00p Eugene 54 DSPRegisterCallback() now returns old callback. 55 56 4 3/26/01 8:34p Eugene 57 Added DSPGetDMAStatus() 58 59 3 4/10/00 9:01p Eugene 60 61 2 3/20/00 3:41p Eugene 62 Added public function prototypes. 63 64 1 3/18/00 11:07p Eugene 65 Initial check-in for DSP driver header file. 66 67 2 3/08/00 2:54p Tian 68 Added stack argument to AIInit 69 70 1 3/07/00 7:08p Eugene 71 Public header file for AI driver/API. 72 73 $NoKeywords: $ 74 75 *---------------------------------------------------------------------------* 76 77 Description 78 ----------- 79 This is the public API definition file for the DSP driver. Applications or 80 OS components which need access to the DSP must include this file. 81 82 *---------------------------------------------------------------------------*/ 83 84 #ifndef __DSP_H__ 85 #define __DSP_H__ 86 87 #ifdef __cplusplus 88 extern "C" { 89 #endif 90 91 /*---------------------------------------------------------------------------* 92 * Includes 93 *---------------------------------------------------------------------------*/ 94 #include <revolution/types.h> 95 96 /*---------------------------------------------------------------------------* 97 * Definitions 98 *---------------------------------------------------------------------------*/ 99 100 #define DSP_TASK_FLAG_CLEARALL 0x00000000 // zero all flags 101 #define DSP_TASK_FLAG_ATTACHED 0x00000001 // Indicates task is in the list. Asserted by DSPAddTask(). Cleared by __DSP_remove_task(). 102 #define DSP_TASK_FLAG_CANCEL 0x00000002 // Asserted by DSPCancelTask(). Marks a task for cancellation/removal. 103 104 #define DSP_TASK_STATE_INIT 0 // task has never been run before 105 #define DSP_TASK_STATE_RUN 1 // task is running 106 #define DSP_TASK_STATE_YIELD 2 // task has yielded control 107 #define DSP_TASK_STATE_DONE 3 // task is finished and has been culled from list 108 109 /*---------------------------------------------------------------------------* 110 * Types/Declarations 111 *---------------------------------------------------------------------------*/ 112 113 114 // All DSP callbacks now pass a pointer to the parent task 115 typedef void (*DSPCallback)(void *task); 116 117 typedef struct STRUCT_DSP_TASK 118 { 119 volatile u32 state; // state of task 120 volatile u32 priority; 121 volatile u32 flags; 122 123 u16 *iram_mmem_addr; // start of IRAM image in main mem 124 u32 iram_length; // length of DRAM image, in bytes 125 u32 iram_addr; // destination address in DSP (u16 words) 126 127 u16 *dram_mmem_addr; // start of DRAM image in main mem 128 u32 dram_length; // length of DRAM image, in bytes 129 u32 dram_addr; // destination address in DSP (u16 words) 130 131 u16 dsp_init_vector; // start vector of task on first execution 132 u16 dsp_resume_vector; // start vector of task when resuming after context switch 133 134 DSPCallback init_cb; // callback for init state 135 DSPCallback res_cb; // callback for resume state 136 DSPCallback done_cb; // callback for done state 137 DSPCallback req_cb; // callback for general interrupt-driven requests from DSP 138 139 struct STRUCT_DSP_TASK *next; // linked list - next task (NULL if last) 140 struct STRUCT_DSP_TASK *prev; // linked list - prev task (NULL if first) 141 142 OSTime t_context; 143 OSTime t_task; 144 145 } DSPTaskInfo; 146 147 148 // Note that storage for the IRAM and DRAM images must be provided by the 149 // task's owner. 150 151 152 /*---------------------------------------------------------------------------* 153 * Globals 154 *---------------------------------------------------------------------------*/ 155 156 /*---------------------------------------------------------------------------* 157 * Macros 158 *---------------------------------------------------------------------------*/ 159 160 #define DSPGetTaskState(t) ((t)->state) // u32 value 161 #define DSPGetTaskPriority(t) ((t)->priority) // u32 value 162 #define DSPSetTaskPriority(t,x) ((t)->priority|=(x)) // x is a u32 value 163 164 /*---------------------------------------------------------------------------* 165 * Function Prototypes 166 *---------------------------------------------------------------------------*/ 167 168 void DSPInit (void); 169 BOOL DSPCheckInit (void); 170 171 void DSPReset (void); 172 void DSPAssertInt (void); 173 174 void DSPHalt (void); 175 void DSPUnhalt (void); 176 177 u32 DSPReadCPUToDSPMbox (void); 178 u32 DSPReadMailFromDSP (void); 179 180 void DSPSendMailToDSP (u32 mail); 181 182 u32 DSPCheckMailToDSP (void); 183 u32 DSPCheckMailFromDSP (void); 184 185 u32 DSPGetDMAStatus (void); 186 187 DSPTaskInfo *DSPAddTask (DSPTaskInfo *task); 188 DSPTaskInfo *DSPCancelTask (DSPTaskInfo *task); 189 DSPTaskInfo *DSPAssertTask (DSPTaskInfo *task); 190 191 192 // for debugging 193 194 DSPTaskInfo *__DSPGetCurrentTask(void); 195 196 197 #ifdef __cplusplus 198 } 199 #endif 200 201 #endif // __DSP_H__ 202