2 * Copyright (c) 2003 Cray Inc.
4 * The contents of this file is proprietary information of Cray Inc.
5 * and may not be disclosed without prior written consent.
9 * This code is licensed under the GNU General Public License,
10 * Version 2. See the file COPYING for more details.
16 #include <rca/l0rca_config.h>
20 * Macros to read/write Seastar Scratch RAM for everyone else.
22 #define SSMEMPUT(dest,src,nb) memcpy((void *)dest,(void *)src,nb)
23 #define SSMEMGET(dest,src,nb) memcpy((void *)dest,(void *)src,nb)
25 #define SSPUT64(to_ptr,value) (*(to_ptr) = (value))
26 #define SSPUT32(to_ptr,value) (*(to_ptr) = (value))
28 #define SSGET64(from_ptr,to_var) ((to_var) = *(from_ptr))
29 #define SSGET32(from_ptr,to_var) ((to_var) = *(from_ptr))
31 /* TODO - Revisit these later */
32 #define LOCK_CHANNEL(chn_num)
33 #define UNLOCK_CHANNEL(chn_num)
35 typedef int (*l0rca_down_handle_t)(int chn_num, rs_event_t* buf, int32_t num);
36 typedef int (*l0rca_up_handle_t)(int chn_num);
38 typedef struct l0rca_ch_status {
39 uint32_t num_obj; /* number of objects */
40 uint32_t ridx; /* read index */
41 uint32_t widx; /* write index */
43 rs_event_t* ch_buf_ptr;
48 * TODO - All API calls defined here may not be implemented in l0rca.c.
49 * These are to be implemented as needed.
53 * download means data transfer from the L0 to the Opteron
54 * upload means data transfer from the Opteron to the LO;
57 #ifdef STANDALONE_DIAGS
59 * Checks if the channel is ready or not (full).
60 * Argument: int channel
62 * 1 if ready (not_full)
65 int l0rca_ch_send_ready(int ch_num);
68 * Clears l0rca_early_cfg.initialized.
69 * This function is required for memtest. Memtest has to move the location
70 * of the storage area for the config in order to move on to the next
71 * region to do the memory test.
73 void l0rca_clear_initialized(void);
77 * Function: l0rca_init_config
79 * Description: Read L0 - RCA communication config structure and populate
80 * our personal copy. If there is any error, the OS panics
81 * as not being able to communicate with L0 is a total disaster.
82 * If already initialized then returns siliently.
88 void l0rca_init_config(void);
91 * Function: register_ch_down
93 * Description: Register function for the download channel. It is expected that
94 * there be at most one registered user for a download channel. This user
95 * provides a callback to be invoked when data from L0 arrives on the channel.
97 * Arguments: int ch_num IN: channel number to register on
98 * l0rca_down_handle_t handler IN: callback routine
99 * int poll IN: if > zero - duration in ms to check for event
100 * if = zero - event arrival is interrupt driven.
101 * if < zero - do nothing. It is assumed that the user
102 * has her own means to check for event arrival.
104 * Returns: EBUSY - If another user is already registered.
105 * zero (SUCCESS) otherwise.
107 int register_ch_down(int ch_num, l0rca_down_handle_t handler, int poll);
110 * Function: unregister_ch_down
112 * Description: Unregister function for the download channel. Use to indicate
113 * that the channel is no longer to be used.
115 * Arguments: int ch_num IN: channel number to unregister
117 * Returns: zero (SUCCESS)
119 int unregister_ch_down(int ch_num);
122 * Function: register_ch_up
124 * Description: Register function for the upload channel. It is expected that
125 * there be at most one registered user for an upload channel. This user
126 * provides a callback to be invoked when the buffer drains below tshhld
127 * (only if the buffer became full last time the tshhld was crossed)
129 * Arguments: int ch_num IN: channel number to register on
130 * l0rca_up_handle_t handler IN: callback routine
131 * int tshhld IN: buffer to drain before invoking callback; ignored
132 * if poll is negative.
133 * int poll IN: if > zero - duration in ms to check for buffer drain
134 * if = zero - tx done interrupt invokes callback
135 * if < zero - do nothing. It is assumed that the user
136 * has her own means to check for buffer drain
138 * Returns: -EBUSY - If another user is already registered.
139 * -EINVAL - if ch_num is not in range.
140 * zero (SUCCESS) otherwise.
142 int register_ch_up(int ch_num, l0rca_up_handle_t handler, int tshhld, int poll);
145 * Function: unregister_ch_up
147 * Description: Unregister function for the download channel. Use to indicate
148 * that the channel is no longer to be used.
150 * Arguments: int ch_num IN: channel number to unregister
152 * Returns: zero (SUCCESS)
154 int unregister_ch_up(int ch_num);
157 * Function: ch_send_data
159 * Description: Sends data towards the L0.
160 * The data that buf points to is sent as the payload in an rs_event structure.
161 * The header is a separate parameter and the send routine directly copies
162 * the header and the data into the circular buffer, thus avoiding a copy.
164 * Arguments: int ch_num IN: channel number on which to send data
165 * rs_event_t *ev_hdr IN: Header without len & timestamp
166 * void* buf IN: Buffer with data
167 * unsigned int len IN: length of data to transfer
169 * Returns: EBUSY - If the circular channel buffer is full.
170 * EINVAL - if no user registered on the channel (Debug only)
171 * EFAULT - if buf or ev_hdr is NULL (Debug only)
172 * E2BIG - if len exceeds max event payload (RS_MSG_LEN) (Debug only)
173 * zero (SUCCESS) otherwise.
175 * Notes: data in buf will be copied to the channel buffer, therfore, upon
176 * return, user can free the buf.
178 int ch_send_data(int ch_num, const rs_event_t *ev_hdr,
179 void* buf, unsigned int len);
182 * Function: ch_send_event
184 * Description: Sends an event to L0.
186 * Arguments: int ch_num IN: channel number on which to send the event
187 * const rs_event_t *evp IN: EVent to send
189 * Returns: -EINVAL - if no user registered on the channel (Debug only)
190 * -EFAULT - if ev_hdr is NULL (Debug only)
191 * zero - SUCCESS, event sent.
192 * +EBUSY - Event not sent. Sender should retry.
194 * Notes: The event will be copied to the channel buffer, therfore, upon
195 * return, user may free the space associated with the event
197 int ch_send_event(int ch_num, const rs_event_t *evp);
200 * Function: ch_status
202 * Description: Obtain status on the channel
204 * Arguments: int ch_num IN: channel number for which to obtain status
205 * Arguments: l0rca_ch_status_t *st OUT: status of the channel.
207 * Returns: zero (SUCCESS).
209 * Notes: The status represents the snapshot at the time of invocation.
211 int ch_status(int ch_num, l0rca_ch_status_t *st);
214 * Function: l0rca_ch_get_event
216 * Description: Read the next available event (if any). This allows the caller
217 * to check for incoming events. It is usefult for those callers
218 * that do not have a receive callback.
220 * Arguments: int ch_num IN: channel number from which to return event
221 * Arguments: rs_event_t *evp: Pointer where the event may be placed
223 * Returns: 0 or 1 - No of events returned (0 ==> No event otherwise always 1)
224 * < 0 - errors such as channel not registered etc.
226 * Note: The receive callback is the preferred way to handle incoming events.
227 * This API call should only be used in cases where a receive callback
228 * mechanism is not feasible. For example, when interupts are disabled and
229 * incoming events need to be serviced. An example user is a kernel
232 int l0rca_ch_get_event(int ch_num, rs_event_t *evp);
235 * Function: l0rca_poll_callback
237 * Description: Scan the incoming channels and call the receive callback
238 * (if any) in case an event is pending to be processed.
239 * Update the read pointer. Next scan the outgoing channels
240 * and if the channel was full, call the transmit done callback
241 * so that events may be sent.
245 * Returns: 0 if no events were processed, else 1.
247 * Note: It is possible that this routine is called from interrupt
248 * context. The callbacks invoked *must* not block.
250 int l0rca_poll_callback(void);
253 * Function: l0rca_get_proc_id
255 * Description: Return the node/processor id.
259 * Returns: The proc id.
261 rs_node_t l0rca_get_proc_id(void);
264 * Function: l0rca_get_max_xyz
266 * Description: Returns the current system dimensions. This information
267 * can be used find the coordinates of the node in the system.
269 * Arguments: int32_t *mx OUT: The x value is stored here after return
270 * int32_t *my OUT: The y value is stored here after return
271 * int32_t *mz OUT: The z value is stored here after return
273 * Returns: No return value.
275 void l0rca_get_max_xyz(int32_t *mx, int32_t *my, int32_t *mz);
278 * Function: l0rca_event_data
280 * Description: Return a pointer to the data portion and length of the
281 * data portion of the event.
283 * Arguments: rs_event_t *evp IN: Event whose data is of interest
284 * void **data OUT: Upon return will point to data portion of event
285 * int32_t *len OUT: Upon return will have the length of the data
286 * portion of the event
288 * Returns: No Return Value.
290 void l0rca_event_data(rs_event_t *evp, void **data, int32_t *len);
294 extern int l0_gdb_init(void);
295 extern int l0rca_kgdb_down_getc(void);
296 extern int gdb_hook(void);
297 extern int gdb_getc(int wait);
298 extern int gdb_putc(char chr);
299 extern int putDebugPacket(char *buf, int n);
302 #endif /* __RCA_L0_H__ */