1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - MB - include
3   File:     mb_task.h
4 
5   Copyright 2007-2008 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   $Date:: 2008-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16  *---------------------------------------------------------------------------*/
17 
18 #if	!defined(NITRO_MB_TASK_H_)
19 #define NITRO_MB_TASK_H_
20 
21 
22 #if	defined(__cplusplus)
23 extern  "C"
24 {
25 #endif
26 
27 
28 /* constant ---------------------------------------------------------------- */
29 
30 /* Expanded definitions for task thread priority levels */
31     /* Specify a priority level just 1 higher than the caller */
32 #define MB_TASK_PRIORITY_ABOVE  (OS_THREAD_PRIORITY_MAX + 1)
33     /* Specify a priority level just 1 lower than the caller */
34 #define MB_TASK_PRIORITY_BELOW  (OS_THREAD_PRIORITY_MAX + 2)
35     /* Specify the same priority level as the caller */
36 #define MB_TASK_PRIORITY_NORMAL (OS_THREAD_PRIORITY_MAX + 3)
37 
38 #define MB_TASK_WORK_MIN	(sizeof(OSThread) + 256)
39 
40 
41 /* struct ------------------------------------------------------------------ */
42 
43     struct MBiTaskInfo_tag;
44 
45     typedef void (*MB_TASK_FUNC) (struct MBiTaskInfo_tag *);
46 
47 /*
48  * The task information structure to request to the task thread.
49  */
50     typedef struct MBiTaskInfo_tag
51     {
52 /* Private: */
53         struct MBiTaskInfo_tag *next;  /* Next element as list */
54         u32     busy:1;                /* If now processing, set 1 */
55         u32     priority:31;           /* Thread priority */
56         MB_TASK_FUNC task;             /* Task function */
57         MB_TASK_FUNC callback;         /* Callback */
58 /* Public: */
59         u32     param[4];              /* User-defined argument and return-value */
60     }
61     MBiTaskInfo;
62 
63 
64 
65 /* Function ---------------------------------------------------------------- */
66 
67 
68 /*---------------------------------------------------------------------------*
69   Name:         MBi_InitTaskThread
70 
71   Description:  Starts a task thread.
72 
73   Arguments:    p_work:     Internal work buffer.
74                            Used internally until MBi_EndTaskThread() completes.
75                 size:       Byte size of p_work.
76                            Must be greater than MB_TASK_WORK_MIN; size - MB_TASK_WORK_MIN is used by the stack.
77 
78 
79   Returns:      None.
80  *---------------------------------------------------------------------------*/
81     void    MBi_InitTaskThread(void *p_work, u32 size);
82 
83 /*---------------------------------------------------------------------------*
84   Name:         MBi_IsTaskAvailable
85 
86   Description:  Checks if a task thread is currently available.
87 
88   Arguments:    None.
89 
90   Returns:      TRUE if currently available, and FALSE otherwise.
91  *---------------------------------------------------------------------------*/
92     BOOL    MBi_IsTaskAvailable(void);
93 
94 /*---------------------------------------------------------------------------*
95   Name:         MBi_InitTaskInfo
96 
97   Description:  Initializes a task information structure.
98                 Must be called once before using.
99 
100   Arguments:    pt:         Uninitialized task information structure
101 
102   Returns:      None.
103  *---------------------------------------------------------------------------*/
104     void    MBi_InitTaskInfo(MBiTaskInfo * pt);
105 
106 /*---------------------------------------------------------------------------*
107   Name:         MBi_IsTaskBusy
108 
109   Description:  Checks if task information is currently being used.
110 
111   Arguments:    pt:         Task information.
112 
113   Returns:      TRUE if currently being used, and FALSE otherwise.
114  *---------------------------------------------------------------------------*/
115     BOOL    MBi_IsTaskBusy(volatile const MBiTaskInfo * pt);
116 
117 /*---------------------------------------------------------------------------*
118   Name:         MBi_SetTask
119 
120   Description:  Adds a task to an internal thread.
121 
122   Arguments:    pt:         Currently unused task information
123                 task:       Task function
124                 callback:   Callback when task completes (ignored if NULL)
125                 priority:   Thread priority while executing a task
126 
127   Returns:      None.
128  *---------------------------------------------------------------------------*/
129     void    MBi_SetTask(MBiTaskInfo * pt, MB_TASK_FUNC task, MB_TASK_FUNC callback, u32 priority);
130 
131 /*---------------------------------------------------------------------------*
132   Name:         MBi_EndTaskThread
133 
134   Description:  Ends the task thread.
135 
136   Arguments:    callback:   Callback when task thread ends (ignored if NULL)
137                            This callback is called in the state just before the task thread ends, while interrupts are still disabled.
138 
139   Returns:      None.
140  *---------------------------------------------------------------------------*/
141     void    MBi_EndTaskThread(MB_TASK_FUNC callback);
142 
143 
144 #if	defined(__cplusplus)
145 }
146 #endif
147 
148 
149 #endif                                 /* NITRO_MB_TASK_H_ */
150