#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" /* forward declaration */ typedef struct sar_t sar_t; /** * Call back prototype to provide measure to the CE. * \param data the context of the CE RX. * \param rx_params general information on measures (date, from). * \param total_pb_count number of PB available in the frame. * \param chan_data the head of the channel data. * \param chan_data_count the count of PBs in the channel data. * \param false_pb_count number of false PBs (CRC error) inside the frame. * \param ber_sum sum of each BER of each PBs with no CRC error inside the * frame */ typedef void (*sar_measurement_cb_t) (void *data, pbproc_rx_params_t *rx_params, uint total_pb_count, pb_t *chan_data, uint chan_data_count, u8 false_pb_count, u32 ber_sum); /** * 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, u32 seed); /** * Release all the data used in the sar. * \param ctx the sar context. */ void sar_uninit (sar_t *ctx); /** * Initialise the SAR callback for DATA reception. * \param ctx the SAR context * \param user the upper layer data context. * * This should be called once the reassembly process has been done. */ void sar_init_data_context (sar_t *ctx, void *user); /** * Initialise the SAR callback for MME reception. * \param ctx the SAR context * \param user the upper layer MSG context. * * This should be called once the reassembly process has been done. */ void sar_init_mme_context (sar_t *ctx, void *user); /** * Initialise the SAR callback for Measure reception. * \param ctx the SAR context * \param user the upper layer MSG context. * * This only store the user data from the client in the SAR context. Two * others API are available to provide the function to call on BER measurement * and Channel data. */ void sar_init_measure_context (sar_t *ctx, void *user); /** * Initialise the SAR with the function to call to inform when the MME is * provided to the PB Processing layer. * \param ctx the SAR context * \param sar_seg_done the function to call. * * When the callback is called the MME is still not sent by the PBProc but * only provided to it. The PBProc has for job to sent it when it have the * possibility on the medium. */ void sar_init_segmentation_mme_cb (sar_t *ctx, sar_segmentation_done_cb_t sar_mme_seg_done); /** * Initialise the SAR with the function to call to inform when the DATA is * provided to the PB Processing layer. * \param ctx the SAR context * \param sar_seg_done the function to call. * * When the callback is called the DATA is still not sent by the PBProc but * only provided to it. The PBProc has for job to sent it when it have the * possibility on the medium. */ 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. */ 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 SAR to call the function on each new frame available. * \param ctx the SAR context * \param sar_rea_done function to call. * \param data a boolean to indicate if it is a DATA stream or MME. */ void sar_init_reassembly_ul (sar_t *ctx, sar_reassembly_done_cb_t sar_rea_done, bool data); /** * Initialise the SAR to call the function on each new MME available. * \param ctx the SAR context * \param sar_mme_reassembly_done function to call. */ 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); } /** * Initialise the SAR to call the function on each new DATA available. * \param ctx the SAR context * \param sar_data_reassembly_done function to call. */ 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); } /** * Add a received MPDU RX to be processed. * \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); /** * Add a Mac Frame to send by over the medium. * \param ctx sar context * \param buffer the buffer containing the Mac Frame. * \param length the length of the Mac Frame. * \param mfs the MFS to stock the PB generated * \param user_data opaque object. * \param arrival_time_ntb the arrival time of the MSDU in the station. * * user_data is an opaque object given back once the segmentation is done. */ void sar_msdu_add (sar_t *ctx, u8 *buffer, u16 length, mfs_tx_t *mfs, void *user_data, u32 arrival_time_ntb); /** * Add an MFS to the SAR expiration mechanism. * \param ctx the SAR context * \param mfs the MFS to add to the SAR. * * Always called in DSR context. */ void sar_mfs_add (sar_t *ctx, mfs_t *mfs); /** * Put the MFS in the release state. * \param ctx the SAR context * \param mfs the MFS to remove from the SAR. */ void sar_mfs_remove (sar_t *ctx, mfs_t *mfs); /** * Initialise the SAR to call the function on beacon reception. * \param ctx the SAR context * \param user_data * \param uf_upper_layer function to call */ void sar_init_beacon_cb (sar_t *sar, void *user_data, sar_beacon_cb_t uf); /** * Function to receive a beacon from the medium. * \param sar the SAR context * \param pb pb containing the beacon * \param params the rx params. * * This function is called by the pbproc using a callback. */ 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 main loop. * \param sar the SAR context. */ void sar_launch (sar_t *sar); /** * 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); /** * SAR function callback to release a MFS. * \param ctx the SAR context. * \param mfs the MFS to release. * * \warn: This function should only post a message in SAR's mailbox. */ void sar_mfs_cmd (sar_t *ctx, mfs_tx_t *mfs); /** * Remove the MFS from Datapath layers. * \param ctx the context. * \param mfs the MFS. * * It removes the MFS from the CA. * Request the PBProc to release all the PBs. * Remove the MFS from the expiration mechanism. * Remove the MFS from the STORE. * * \warn the user reference must be released by the user. * This function should be always called with DSR locked. */ void sar_mfs_free_tx (sar_t *ctx, mfs_tx_t *mfs); /** * Remove the MFS from the datapath layers. * \param ctx the context. * \param mfs the MFS RX to remove. * * Remove the MFS from the expiration mechanism. * Remove the MFS from the STORE. * * \warn the user reference must be released by the user. * This function should be always called with DSR locked. */ void sar_mfs_free_rx (sar_t *ctx, mfs_rx_t *mfs); END_DECLS #endif /*MAC_SAR_SAR_H_*/