X-Git-Url: http://v3vee.org/palacios/gitweb/gitweb.cgi?a=blobdiff_plain;f=kitten%2Finclude%2Frca%2Frca_l0.h;fp=kitten%2Finclude%2Frca%2Frca_l0.h;h=ce7cb058bf4022b920941bf10ec548a601842be1;hb=66a1a4c7a9edcd7d8bc207aca093d694a6e6b5b2;hp=0000000000000000000000000000000000000000;hpb=f7cf9c19ecb0a589dd45ae0d2c91814bd3c2acc2;p=palacios.git diff --git a/kitten/include/rca/rca_l0.h b/kitten/include/rca/rca_l0.h new file mode 100644 index 0000000..ce7cb05 --- /dev/null +++ b/kitten/include/rca/rca_l0.h @@ -0,0 +1,302 @@ +/* + * Copyright (c) 2003 Cray Inc. + * + * The contents of this file is proprietary information of Cray Inc. + * and may not be disclosed without prior written consent. + * + */ +/* + * This code is licensed under the GNU General Public License, + * Version 2. See the file COPYING for more details. + */ + +#ifndef __RCA_L0_H__ +#define __RCA_L0_H__ + +#include + + +/* + * Macros to read/write Seastar Scratch RAM for everyone else. + */ +#define SSMEMPUT(dest,src,nb) memcpy((void *)dest,(void *)src,nb) +#define SSMEMGET(dest,src,nb) memcpy((void *)dest,(void *)src,nb) + +#define SSPUT64(to_ptr,value) (*(to_ptr) = (value)) +#define SSPUT32(to_ptr,value) (*(to_ptr) = (value)) + +#define SSGET64(from_ptr,to_var) ((to_var) = *(from_ptr)) +#define SSGET32(from_ptr,to_var) ((to_var) = *(from_ptr)) + +/* TODO - Revisit these later */ +#define LOCK_CHANNEL(chn_num) +#define UNLOCK_CHANNEL(chn_num) + +typedef int (*l0rca_down_handle_t)(int chn_num, rs_event_t* buf, int32_t num); +typedef int (*l0rca_up_handle_t)(int chn_num); + +typedef struct l0rca_ch_status { + uint32_t num_obj; /* number of objects */ + uint32_t ridx; /* read index */ + uint32_t widx; /* write index */ + uint32_t reg_count; + rs_event_t* ch_buf_ptr; +} l0rca_ch_status_t; + +/* + * API defines + * TODO - All API calls defined here may not be implemented in l0rca.c. + * These are to be implemented as needed. + */ + +/* NOTE + * download means data transfer from the L0 to the Opteron + * upload means data transfer from the Opteron to the LO; + */ + +#ifdef STANDALONE_DIAGS +/* + * Checks if the channel is ready or not (full). + * Argument: int channel + * Returns: + * 1 if ready (not_full) + * 0 if not ready + */ +int l0rca_ch_send_ready(int ch_num); + +/* + * Clears l0rca_early_cfg.initialized. + * This function is required for memtest. Memtest has to move the location + * of the storage area for the config in order to move on to the next + * region to do the memory test. + */ +void l0rca_clear_initialized(void); +#endif + +/* + * Function: l0rca_init_config + * + * Description: Read L0 - RCA communication config structure and populate + * our personal copy. If there is any error, the OS panics + * as not being able to communicate with L0 is a total disaster. + * If already initialized then returns siliently. + * + * Arguments: None. + * + * Returns: None + */ +void l0rca_init_config(void); + +/* + * Function: register_ch_down + * + * Description: Register function for the download channel. It is expected that + * there be at most one registered user for a download channel. This user + * provides a callback to be invoked when data from L0 arrives on the channel. + * + * Arguments: int ch_num IN: channel number to register on + * l0rca_down_handle_t handler IN: callback routine + * int poll IN: if > zero - duration in ms to check for event + * if = zero - event arrival is interrupt driven. + * if < zero - do nothing. It is assumed that the user + * has her own means to check for event arrival. + * + * Returns: EBUSY - If another user is already registered. + * zero (SUCCESS) otherwise. + */ +int register_ch_down(int ch_num, l0rca_down_handle_t handler, int poll); + +/* + * Function: unregister_ch_down + * + * Description: Unregister function for the download channel. Use to indicate + * that the channel is no longer to be used. + * + * Arguments: int ch_num IN: channel number to unregister + * + * Returns: zero (SUCCESS) + */ +int unregister_ch_down(int ch_num); + +/* + * Function: register_ch_up + * + * Description: Register function for the upload channel. It is expected that + * there be at most one registered user for an upload channel. This user + * provides a callback to be invoked when the buffer drains below tshhld + * (only if the buffer became full last time the tshhld was crossed) + * + * Arguments: int ch_num IN: channel number to register on + * l0rca_up_handle_t handler IN: callback routine + * int tshhld IN: buffer to drain before invoking callback; ignored + * if poll is negative. + * int poll IN: if > zero - duration in ms to check for buffer drain + * if = zero - tx done interrupt invokes callback + * if < zero - do nothing. It is assumed that the user + * has her own means to check for buffer drain + * + * Returns: -EBUSY - If another user is already registered. + * -EINVAL - if ch_num is not in range. + * zero (SUCCESS) otherwise. + */ +int register_ch_up(int ch_num, l0rca_up_handle_t handler, int tshhld, int poll); + +/* + * Function: unregister_ch_up + * + * Description: Unregister function for the download channel. Use to indicate + * that the channel is no longer to be used. + * + * Arguments: int ch_num IN: channel number to unregister + * + * Returns: zero (SUCCESS) + */ +int unregister_ch_up(int ch_num); + +/* + * Function: ch_send_data + * + * Description: Sends data towards the L0. + * The data that buf points to is sent as the payload in an rs_event structure. + * The header is a separate parameter and the send routine directly copies + * the header and the data into the circular buffer, thus avoiding a copy. + * + * Arguments: int ch_num IN: channel number on which to send data + * rs_event_t *ev_hdr IN: Header without len & timestamp + * void* buf IN: Buffer with data + * unsigned int len IN: length of data to transfer + * + * Returns: EBUSY - If the circular channel buffer is full. + * EINVAL - if no user registered on the channel (Debug only) + * EFAULT - if buf or ev_hdr is NULL (Debug only) + * E2BIG - if len exceeds max event payload (RS_MSG_LEN) (Debug only) + * zero (SUCCESS) otherwise. + * + * Notes: data in buf will be copied to the channel buffer, therfore, upon + * return, user can free the buf. + */ +int ch_send_data(int ch_num, const rs_event_t *ev_hdr, + void* buf, unsigned int len); + +/* + * Function: ch_send_event + * + * Description: Sends an event to L0. + * + * Arguments: int ch_num IN: channel number on which to send the event + * const rs_event_t *evp IN: EVent to send + * + * Returns: -EINVAL - if no user registered on the channel (Debug only) + * -EFAULT - if ev_hdr is NULL (Debug only) + * zero - SUCCESS, event sent. + * +EBUSY - Event not sent. Sender should retry. + * + * Notes: The event will be copied to the channel buffer, therfore, upon + * return, user may free the space associated with the event + */ +int ch_send_event(int ch_num, const rs_event_t *evp); + +/* + * Function: ch_status + * + * Description: Obtain status on the channel + * + * Arguments: int ch_num IN: channel number for which to obtain status + * Arguments: l0rca_ch_status_t *st OUT: status of the channel. + * + * Returns: zero (SUCCESS). + * + * Notes: The status represents the snapshot at the time of invocation. + */ +int ch_status(int ch_num, l0rca_ch_status_t *st); + +/* + * Function: l0rca_ch_get_event + * + * Description: Read the next available event (if any). This allows the caller + * to check for incoming events. It is usefult for those callers + * that do not have a receive callback. + * + * Arguments: int ch_num IN: channel number from which to return event + * Arguments: rs_event_t *evp: Pointer where the event may be placed + * + * Returns: 0 or 1 - No of events returned (0 ==> No event otherwise always 1) + * < 0 - errors such as channel not registered etc. + * + * Note: The receive callback is the preferred way to handle incoming events. + * This API call should only be used in cases where a receive callback + * mechanism is not feasible. For example, when interupts are disabled and + * incoming events need to be serviced. An example user is a kernel + * debugger. + */ +int l0rca_ch_get_event(int ch_num, rs_event_t *evp); + +/* + * Function: l0rca_poll_callback + * + * Description: Scan the incoming channels and call the receive callback + * (if any) in case an event is pending to be processed. + * Update the read pointer. Next scan the outgoing channels + * and if the channel was full, call the transmit done callback + * so that events may be sent. + * + * Arguments: None + * + * Returns: 0 if no events were processed, else 1. + * + * Note: It is possible that this routine is called from interrupt + * context. The callbacks invoked *must* not block. + */ +int l0rca_poll_callback(void); + +/* + * Function: l0rca_get_proc_id + * + * Description: Return the node/processor id. + * + * Arguments: None + * + * Returns: The proc id. + */ +rs_node_t l0rca_get_proc_id(void); + +/* + * Function: l0rca_get_max_xyz + * + * Description: Returns the current system dimensions. This information + * can be used find the coordinates of the node in the system. + * + * Arguments: int32_t *mx OUT: The x value is stored here after return + * int32_t *my OUT: The y value is stored here after return + * int32_t *mz OUT: The z value is stored here after return + * + * Returns: No return value. + */ +void l0rca_get_max_xyz(int32_t *mx, int32_t *my, int32_t *mz); + +/* + * Function: l0rca_event_data + * + * Description: Return a pointer to the data portion and length of the + * data portion of the event. + * + * Arguments: rs_event_t *evp IN: Event whose data is of interest + * void **data OUT: Upon return will point to data portion of event + * int32_t *len OUT: Upon return will have the length of the data + * portion of the event + * + * Returns: No Return Value. + */ +void l0rca_event_data(rs_event_t *evp, void **data, int32_t *len); + + +#ifdef __KERNEL__ +extern int l0_gdb_init(void); +extern int l0rca_kgdb_down_getc(void); +extern int gdb_hook(void); +extern int gdb_getc(int wait); +extern int gdb_putc(char chr); +extern int putDebugPacket(char *buf, int n); +#endif + +#endif /* __RCA_L0_H__ */