#ifndef MAC_SAR_SAR_H_ #define MAC_SAR_SAR_H_ /* Cesar project {{{ * * Copyright (C) 2007 Spidcom * * <<>> * * }}} */ /** * \file mac/sar/sar.h * \brief Public intefaces of the SAR. * \ingroup mac/sar/ * */ #include "mac/common/store.h" #include "mac/pbproc/pbproc.h" #include "mac/sar/sar_mfs_expiration_cb.h" #include "mac/sar/sar_mf.h" #define SAR_THREAD_PRIORITY 9 #define SAR_THREAD_STACK_SIZE CYGNUM_HAL_STACK_SIZE_TYPICAL /* forward declaration */ typedef struct sar_t sar_t; /** * Pb measurement RX callback for Channel estimation. * This call back will return one or two block in order to insert all the * measurements contained in each PB of the mpdu received. * Two cases can happen, the first the pb_nb is lesser than the blk capacity, * this callback will return only a blk pointed by the first and the last * pointer. * In the second case the quantity of PB are greater than one blk capacity, this * callback will return two blk (chained) the first pointed by the first pointer * and the last one by the last pointer. * * It provides the chandata to the CE provided by the pbproc. * * \param user User data * \param rx_params Frame control information to know date and tonemap used * \param number of pbs * \param first blk to insert the measurements. * \param last blk to insert the measurements. * \param chan_data_first the first chandata PB. * \param nb_chandata the quantitity of chandata PBs. * \param blk_offset the first offset to write the measure in the blk. * * \return boolean to indicate if a block had been returned or not. */ typedef bool (*sar_measurement_cb_t) (void *user, pbproc_rx_params_t *rx_params, uint pb_nb, blk_t **first, blk_t **last, pb_t *chan_data_first, uint nb_chandata, uint *blk_offset); /** * Segmentation job done for the segmentation module, it send a data to inform * the upper layer that a job had been processed. * * \param user upper layer context * \param buffer the buffer which is no more used. * \param user_data data provided by the upper layer on the MSDU add. * * The MFS reference is given to the CL it do not make a addref on it. */ typedef void (*sar_segmentation_done_cb_t) (void *user, u8* buffer, void *user_data); /** * Inform the upper layer that the buffer given in parameter is not used anymore. * * \param user upper layer context pointer * \param buffer the buffer which is no more used. * \param length the length of the buffer. * \param mfs the MFS used to reassembly the packet. * \param encrypted true if the MF has been encrypted, false otherwise. This * is only valid for the MME, the DATA are dropped if it is not encrypted. * * The MFS reference is given to the CL it do not make a addref on it. */ typedef void (*sar_reassembly_done_cb_t) (void *user, u8* buffer, uint length, mfs_rx_t *mfs, bool encrypted); /** * Provides the beacon to the Control Plane * * \param user user data * \param beacon the beacon data * \param params the rx params at the pb reception */ typedef void (*sar_beacon_cb_t) (void *user, pb_beacon_t *pb, pbproc_rx_beacon_params_t *params); BEGIN_DECLS /** * Initialize the SAR context. * * \param mac_store the mac store * \param pbproc the PBProc context. * \param ca the Channel Access context. * \return the SAR context. */ sar_t * sar_init (mac_store_t *mac_store, pbproc_t *pbproc, ca_t *ca); /** * Release all the data used in the sar. * * \param ctx the sar context. */ void sar_uninit (sar_t *ctx); /** * Add the upper data layer context to the SAR. It allows the SAR to use * the context in the callbacks to this layer. * * \param ctx the SAR context * \param user the upper layer data context. */ void sar_init_data_context (sar_t *ctx, void *user); /** * Add the upper data layer context to the SAR. It allows the SAR to use * the context in the callbacks to this layer. * * \param ctx the SAR context * \param user the upper layer MSG context. */ void sar_init_mme_context (sar_t *ctx, void *user); /** * Add the upper data layer context to the SAR. It allows the SAR to use * the context in the callbacks to this layer. * * \param ctx the SAR context * \param user the upper layer MSG context. */ void sar_init_measure_context (sar_t *ctx, void *user); /** * Used by the upper layers to send or received messages. * * \param ctx the SAR context * \param sar_seg_done used by the segmentation to inform the upper layer the * buffer is not used anymore. */ void sar_init_segmentation_mme_cb (sar_t *ctx, sar_segmentation_done_cb_t sar_mme_seg_done); /** * Used to inform the upper layer when a Data has been provided to the CA. * * \param ctx the sar context * \param sar_seg_done used by the segmentation to inform the upper layer the * buffer is not used anymore. */ void sar_init_segmentation_data_cb (sar_t *ctx, sar_segmentation_done_cb_t sar_data_seg_done); /** * Initialize the callback to send the measurement contained in the PBs. * * \param ctx the SAR context * \param sar_measurement the function to call to get the buffers to stock * the measurements. */ void sar_init_measurement_cb (sar_t *ctx, sar_measurement_cb_t sar_measurement); /** * Add a buffer address to the SAR to bridge pending jobs. * * \param ctx the SAR context to add a buffer * \param buffer_addr the buffer address to add to the SAR in order to bridge * the pending jobs. * \param data if it is a data buffer. */ void sar_buffer_add (sar_t *ctx, u8* buffer_addr, bool data); /** * Add a buffer address to the SAR to bridge pending jobs. * * \param ctx the SAR context to add a buffer * \param buffer_addr the buffer address to add to the SAR in order to bridge * the pending jobs. */ extern inline void sar_data_buffer_add (sar_t *ctx, u8* buffer_addr) { sar_buffer_add (ctx, buffer_addr, true); } /** * Add a buffer address to the SAR to bridge pending jobs. * * \param ctx the SAR context to add a buffer * \param buffer_addr the buffer address to add to the SAR in order to bridge * the pending jobs. */ extern inline void sar_mme_buffer_add (sar_t *ctx, u8* buffer_addr) { sar_buffer_add (ctx, buffer_addr, false); } /** * Initialise the callback pointer and return the context to the Upper layers * * \param ctx the SAR context * \param sar_rea_done inform the upper layers that the buffer is filled. * \param data a boolean to indicate if it is a data stream or not. */ void sar_init_reassembly_ul (sar_t *ctx, sar_reassembly_done_cb_t sar_rea_done, bool data); /** * Initialize the callback pointer and return the context to the Control Plane * to manage MME data * * \param ctx the SAR context * \param sar_mme_reassembly_done the function to call when the bridge DMA ends a job. */ extern inline void sar_init_reassembly_mme_cb (sar_t *ctx, sar_reassembly_done_cb_t sar_mme_reassembly_done) { sar_init_reassembly_ul (ctx, sar_mme_reassembly_done, false); } /** * Initialize the callback pointer and return the context to the Convergence * layer to manage data * * \param ctx the SAR context * \param sar_data_reassembly_done the function to call when the bridge * DMA ends a job. */ extern inline void sar_init_reassembly_data_cb (sar_t *ctx, sar_reassembly_done_cb_t sar_data_reassembly_done) { sar_init_reassembly_ul (ctx, sar_data_reassembly_done, true); } /** * MPDU RX callback. * \param user user data * \param rx_desc received MPDU block descriptor * * See pbproc_rx_cb_t. */ void sar_mpdu_add (void *user, pbproc_rx_desc_t *rx_desc); /** Call by convergence layer or control plane to add data in transmit data * path * Add new data in the to_tx_list defined in segmentation.h * * \param ctx sar context * \param buffer the buffer address containing the data to segment * \param length the type and length of the data * \param ats_confounder * \param mfs the mfs to stock the PB generated * \param user data to give back when the send done is made. * \param arrival_time_ntb the arrival time of the msdu in the station. */ void sar_msdu_add (sar_t *ctx, u8 *buffer, u16 length, u32 ats_confounder, mfs_tx_t *mfs, void *user_data, u32 arrival_time_ntb); /** Add a MFS to the SAR. * * \param ctx the SAR expiration context * \param mfs the mfs to add to the SAR. */ void sar_mfs_add (sar_t *ctx, mfs_t *mfs); /** Remove a MFS from the SAR * * \param ctx the SAR context * \param mfs the mfs to remove from the SAR. */ void sar_mfs_remove (sar_t *ctx, mfs_t *mfs); /** * Provides the beacon to the Control plane * * \param ctx the SAR context * \param user_data * \param uf upper layer function call */ void sar_init_beacon_cb (sar_t *sar, void *user_data, sar_beacon_cb_t uf); /** * add a beacon to the SAR. * It will provide it to the CP to process the beacon. * * \param sar the SAR context * \param pb pb containing the beacon * \param params the rx params. */ void sar_beacon_add (void *sar, pb_beacon_t *pb, pbproc_rx_beacon_params_t *params); /** * Request the SAR to send a beacon. * * \param ctx the SAR context. * \param beacon the beacon to send. * \param beacon_mfs the MFS use to send the beacon * \param bto_bpsto the address to provide to the pbproc. */ void sar_beacon_send (sar_t *sar, pb_beacon_t *beacon, mfs_tx_t *beacon_mfs, void *bto_bpsto); /** * SAR procedure * Launch the SAR. * * \param sar the SAR context. */ void sar_launch (sar_t *sar); /** * Get the SAR expiration context to add or remove MFS from the SAR expiration * mechanism. * * \param ctx the SAR context * \param cb the callback function to inform the upper layer when a MFS will * expire, not used if the MFS is a PLID kind. */ void sar_init_expiration (sar_t *ctx, sar_mfs_expired_cb_t cb); /** * Remove a station from the SAR and the mac store. * \param ctx the ctx context. * \param tei the station TEI. * * Remove all the MFS from the expiration mechanism of the SAR and ends to * remove the station from the mac store. */ void sar_sta_remove (sar_t *ctx, u8 tei); /** * SAR Activate. * \param ctx the SAR context. * \param activate true to activate, false to disable. */ void sar_activate (sar_t *ctx, bool activate); /** * SAR clean up all the MFS in the store and the SAR. * \param ctx the SAR context. */ void sar_cleanup (sar_t *ctx); END_DECLS #endif /*MAC_SAR_SAR_H_*/