# KE_MSG
[KERNEL]

Message scheduling module. More...

Collaboration diagram for KE_MSG:

## Data Structures
struct | ke_msg
| Message structure. More...
## Defines
#define | KE_BUILD_ID(type, index) ( (ke_task_id_t)(((index) << 8)|(type)) )
| Builds the task identifier from the type and the index of that task.
#define | KE_TYPE_GET(ke_task_id) ((ke_task_id) & 0xFF)
| Retrieves task type from task id.
#define | KE_IDX_GET(ke_task_id) (((ke_task_id) >> 8) & 0xFF)
| Retrieves task index number from task id.
#define | KE_MSG_ALLOC(id, dest, src, param_str) (struct param_str*) ke_msg_alloc(id, dest, src, sizeof(struct param_str))
| Convenient wrapper to ke_msg_alloc().
#define | KE_MSG_ALLOC_VAR(id, dest, src, param_str, var_len) (struct param_str*) ke_msg_alloc(id, dest, src, sizeof(struct param_str) + var_len)
| Convenient wrapper to ke_msg_alloc(), for variable size message parameter structures.
#define | KE_MSG_FREE(param_ptr) ke_msg_free(ke_param2msg((param_ptr)))
| Convenient wrapper to ke_msg_free().
## Typedefs
typedef uint16_t | ke_task_id_t
| Task Identifier. Composed by the task type and the task index.
typedef uint16_t | ke_state_t
| Task State.
typedef uint16_t | ke_msg_id_t
| Message Identifier.
## Enumerations
enum | ke_msg_status_tag { KE_MSG_CONSUMED = 0, KE_MSG_NO_FREE, KE_MSG_SAVED }
| Status returned by a task when handling a message. More...
## Functions
void * | ke_msg_alloc (ke_msg_id_t const id, ke_task_id_t const dest_id, ke_task_id_t const src_id, uint16_t const param_len)
| Allocate memory for a message.
void | ke_msg_send (void const *param_ptr)
| Message sending.
void | ke_msg_send_basic (ke_msg_id_t const id, ke_task_id_t const dest_id, ke_task_id_t const src_id)
| Basic message sending.
void | ke_msg_forward (void const *param_ptr, ke_task_id_t const dest_id, ke_task_id_t const src_id)
| Message forwarding.
void | ke_msg_forward_and_change_id (void const *param_ptr, ke_msg_id_t const msg_id, ke_task_id_t const dest_id, ke_task_id_t const src_id)
| Message forwarding.
void | ke_msg_free (struct ke_msg const *msg)
| Free allocated message.
__INLINE struct ke_msg * | ke_param2msg (void const *param_ptr)
| Convert a parameter pointer to a message pointer.
__INLINE void * | ke_msg2param (struct ke_msg const *msg)
| Convert a message pointer to a parameter pointer.

## Detailed Description

Message scheduling module.

The MSG module implements message scheduling functions.

A kernel message has an ID, a receiver task ID and a source task ID. In most cases, it also has parameters which are defined in a structure dynamically embedded in the message structure, so the whole message will be managed internally as one block.

A message can also have one extra parameter which is referenced in the normal parameter structure. This extra block is assumed to be large by the kernel and will be moved by DMA if needed. This feature allows moving MMPDU from LMAC to UMAC.

In order to send a message, a function first have to allocate the memory for this message. It can be done with the wrapper macro KE_MSG_ALLOC() (which will call ke_msg_alloc()).

The message can then be sent with ke_msg_send(). The kernel will take care of freeing the allocated memory.

If the message has no parameters, the ke_msg_send_basic() function can be used.

## Define Documentation

#define KE_MSG_ALLOC | ( | id,
|  | dest,
|  | src,
|  | param_str |  | ) | (struct param_str*) ke_msg_alloc(id, dest, src, sizeof(struct param_str))

Convenient wrapper to ke_msg_alloc().

This macro calls ke_msg_alloc() and cast the returned pointer to the appropriate structure. Can only be used if a parameter structure exists for this message (otherwise, use ke_msg_send_basic()).

Parameters:

  `[in]` | id | Message identifier
  `[in]` | dest | Destination Identifier
  `[in]` | src | Source Identifier
  `[in]` | param_str | parameter structure tag

Returns:
  Pointer to the parameter member of the ke_msg.

Definition at line 149 of file ke_msg.h.

Referenced by apm_start_cac_req_handler(), apm_start_req_handler(), chan_send_force_idle(), chan_send_pre_switch_ind(), chan_send_roc_exp_ind(), chan_send_survey_ind(), chan_send_switch_ind(), dbg_get_sys_stat_req_handler(), dbg_mem_read_req_handler(), dbg_mem_write_req_handler(), me_beacon_check(), me_chan_ctxt_update(), me_config_monitor_req_handler(), me_config_req_handler(), me_credits_update_ind(), me_rc_stats_req_handler(), me_set_active_req_handler(), me_set_control_port_req_handler(), me_set_ps_disable_req_handler(), me_set_ps_mode_req_handler(), me_sta_add_req_handler(), me_sta_del_req_handler(), me_traffic_ind_req_handler(), mm_add_if_req_handler(), mm_ap_tbtt_move_cb(), mm_ba_add_req_handler(), mm_ba_del_req_handler(), mm_bcn_send_csa_counter_ind(), mm_key_add_req_handler(), mm_ps_change_ind(), mm_remain_on_channel_req_handler(), mm_set_channel_req_handler(), mm_set_p2p_noa_req_handler(), mm_set_p2p_oppps_req_handler(), mm_set_power_req_handler(), mm_set_vif_state_cfm_handler(), mm_sta_add_req_handler(), mm_traffic_req_ind(), mm_version_req_handler(), p2p_go_send_noa_upd_ind(), p2p_update_go_ps_state(), rxu_cntrl_mic_failure(), scan_start_req_handler(), scanu_get_scan_result_req_handler(), scanu_join_cfm_handler(), sm_connect_req_handler(), sm_delete_resources(), tdls_cancel_chan_switch_req_handler(), tdls_chan_switch_req_handler(), tdls_chsw_time_evt(), and tdls_peer_traffic_ind_req_handler().

#define KE_MSG_ALLOC_VAR | ( | id,
|  | dest,
|  | src,
|  | param_str,
|  | var_len |  | ) | (struct param_str*) ke_msg_alloc(id, dest, src, sizeof(struct param_str) + var_len)

Convenient wrapper to ke_msg_alloc(), for variable size message parameter structures.

This macro calls ke_msg_alloc() and cast the returned pointer to the appropriate structure. Can only be used if a parameter structure exists for this message (otherwise, use ke_msg_send_basic()).

Parameters:

  `[in]` | id | Message identifier
  `[in]` | dest | Destination Identifier
  `[in]` | src | Source Identifier
  `[in]` | param_str | parameter structure tag
  `[in]` | var_len | Length of the variable part to be allocated

Returns:
  Pointer to the parameter member of the ke_msg.

Definition at line 170 of file ke_msg.h.

Referenced by rxu_mgt_frame_ind().

#define KE_MSG_FREE | ( | param_ptr |  | ) | ke_msg_free(ke_param2msg((param_ptr)))

Convenient wrapper to ke_msg_free().

This macro calls ke_msg_free() with the appropriate msg pointer as parameter, according to the message parameter pointer passed.

Parameters:

  `[in]` | param_ptr | parameter structure pointer

Definition at line 183 of file ke_msg.h.

## Typedef Documentation

typedef uint16_t ke_msg_id_t

Message Identifier.

The number of messages is limited to 0xFFFF. The message ID is divided in two parts:

- bits[15..10] : task index (no more than 64 tasks supported).
- bits[9..0] : message index (no more that 1024 messages per task).

Definition at line 82 of file ke_msg.h.

## Enumeration Type Documentation

enum ke_msg_status_tag

Status returned by a task when handling a message.

Enumerator:

  KE_MSG_CONSUMED | consumed, msg and ext are freed by the kernel
  KE_MSG_NO_FREE | consumed, nothing is freed by the kernel
  KE_MSG_SAVED | not consumed, will be pushed in the saved queue

Definition at line 97 of file ke_msg.h.

## Function Documentation

__INLINE void* ke_msg2param | ( | struct ke_msg const * | msg | ) |

Convert a message pointer to a parameter pointer.

Parameters:

  `[in]` | msg | Pointer to the ke_msg.

Returns:
  The pointer to the param member

Definition at line 128 of file ke_msg.h.

References ke_msg::param.

Referenced by ipc_emb_kmsg_hdlr(), me_set_active_cfm_handler(), and mm_bcn_transmitted().

void * ke_msg_alloc | ( | ke_msg_id_t const | id,
|  | ke_task_id_t const | dest_id,
|  | ke_task_id_t const | src_id,
|  | uint16_t const | param_len |
| ) |  |  |

Allocate memory for a message.

This primitive allocates memory for a message that has to be sent. The memory is allocated dynamically on the heap and the length of the variable parameter structure has to be provided in order to allocate the correct size.

Several additional parameters are provided which will be preset in the message and which may be used internally to choose the kind of memory to allocate.

The memory allocated will be automatically freed by the kernel, after the pointer has been sent to ke_msg_send(). If the message is not sent, it must be freed explicitly with ke_msg_free().

Allocation failure is considered critical and should not happen.

Parameters:

  `[in]` | id | Message identifier
  `[in]` | dest_id | Destination Task Identifier
  `[in]` | src_id | Source Task Identifier
  `[in]` | param_len | Size of the message parameters to be allocated

Returns:
  Pointer to the parameter member of the ke_msg. If the parameter structure is empty, the pointer will point to the end of the message and should not be used (except to retrieve the message pointer or to send the message)

void ke_msg_forward | ( | void const * | param_ptr,
|  | ke_task_id_t const | dest_id,
|  | ke_task_id_t const | src_id |
| ) |  |  |

Message forwarding.

Forward a message to another task by changing its destination and source tasks IDs.

Parameters:

  `[in]` | param_ptr | Pointer to the parameter member of the message that should be sent.
  `[in]` | dest_id | New destination task of the message.
  `[in]` | src_id | New source task of the message.

void ke_msg_forward_and_change_id | ( | void const * | param_ptr,
|  | ke_msg_id_t const | msg_id,
|  | ke_task_id_t const | dest_id,
|  | ke_task_id_t const | src_id |
| ) |  |  |

Message forwarding.

Forward a message to another task by changing its message, destination and source tasks IDs.

Parameters:

  `[in]` | param_ptr | Pointer to the parameter member of the message that should be sent.
  `[in]` | msg_id | New Id of the message.
  `[in]` | dest_id | New destination task of the message.
  `[in]` | src_id | New source task of the message.

Referenced by scanu_scan_frame_handler().

void ke_msg_free | ( | struct ke_msg const * | msg | ) |

Free allocated message.

Parameters:

  `[in]` | msg | Pointer to the message to be freed (not the parameter member!)

Referenced by bfr_group_update_cfm(), mm_bcn_updated(), mm_scan_channel_end_ind_handler(), and mm_tim_update_proceed().

void ke_msg_send | ( | void const * | param_ptr | ) |

Message sending.

Send a message previously allocated with any ke_msg_alloc()-like functions.

The kernel will take care of freeing the message memory.

Once the function have been called, it is not possible to access its data anymore as the kernel may have copied the message and freed the original memory.

Parameters:

  `[in]` | param_ptr | Pointer to the parameter member of the message that should be sent.

Referenced by apm_start_cac_req_handler(), apm_start_req_handler(), chan_send_force_idle(), chan_send_pre_switch_ind(), chan_send_roc_exp_ind(), chan_send_survey_ind(), chan_send_switch_ind(), dbg_get_sys_stat_req_handler(), dbg_mem_read_req_handler(), dbg_mem_write_req_handler(), ipc_emb_kmsg_hdlr(), me_beacon_check(), me_chan_ctxt_update(), me_config_monitor_req_handler(), me_config_req_handler(), me_credits_update_ind(), me_rc_stats_req_handler(), me_set_active_cfm_handler(), me_set_active_req_handler(), me_set_control_port_req_handler(), me_set_ps_disable_req_handler(), me_set_ps_mode_req_handler(), me_sta_add_req_handler(), me_sta_del_req_handler(), me_traffic_ind_req_handler(), mm_add_if_req_handler(), mm_ap_tbtt_move_cb(), mm_ba_add_req_handler(), mm_ba_del_req_handler(), mm_bcn_send_csa_counter_ind(), mm_key_add_req_handler(), mm_ps_change_ind(), mm_remain_on_channel_req_handler(), mm_set_channel_req_handler(), mm_set_p2p_noa_req_handler(), mm_set_p2p_oppps_req_handler(), mm_set_power_req_handler(), mm_set_vif_state_cfm_handler(), mm_sta_add_req_handler(), mm_traffic_req_ind(), mm_version_req_handler(), p2p_go_send_noa_upd_ind(), p2p_update_go_ps_state(), rxu_cntrl_mic_failure(), rxu_mgt_frame_ind(), scan_start_req_handler(), scanu_get_scan_result_req_handler(), scanu_join_cfm_handler(), sm_connect_req_handler(), tdls_cancel_chan_switch_req_handler(), tdls_chan_switch_req_handler(), tdls_chsw_time_evt(), and tdls_peer_traffic_ind_req_handler().

void ke_msg_send_basic | ( | ke_msg_id_t const | id,
|  | ke_task_id_t const | dest_id,
|  | ke_task_id_t const | src_id |
| ) |  |  |

Basic message sending.

Send a message that has a zero length parameter member. No allocation is required as it will be done internally.

Parameters:

  `[in]` | id | Message identifier
  `[in]` | dest_id | Destination Identifier
  `[in]` | src_id | Source Identifier

Referenced by apm_stop_cac_req_handler(), apm_stop_req_handler(), bfr_group_update_cfm(), chan_conn_less_ctxt_end(), chan_switch_channel(), dbg_set_mod_filter_req_handler(), dbg_set_sev_filter_req_handler(), me_chan_config_req_handler(), me_config_req_handler(), me_set_active_cfm_handler(), me_set_active_req_handler(), me_set_control_port_req_handler(), me_set_ps_disable_req_handler(), me_set_ps_mode_req_handler(), me_sta_del_req_handler(), me_traffic_ind_req_handler(), mm_bcn_updated(), mm_chan_ctxt_unlink_req_handler(), mm_chan_ctxt_update_req_handler(), mm_key_del_req_handler(), mm_remove_if_req_handler(), mm_reset_req_handler(), mm_scan_channel_end_ind_handler(), mm_set_basic_rates_req_handler(), mm_set_beacon_int_req_handler(), mm_set_bss_color_req_handler(), mm_set_bssid_req_handler(), mm_set_dtim_req_handler(), mm_set_edca_req_handler(), mm_set_filter_req_handler(), mm_set_idle_cfm_handler(), mm_set_idle_req_handler(), mm_set_mode_req_handler(), mm_set_mu_edca_req_handler(), mm_set_ps_mode_cfm_handler(), mm_set_ps_options_req_handler(), mm_set_slottime_req_handler(), mm_set_txop_rts_thres_req_handler(), mm_set_uora_req_handler(), mm_set_vif_state_req_handler(), mm_sta_del_req_handler(), mm_start_req_handler(), mm_tim_update_proceed(), ps_disable_cfm(), ps_enable_cfm(), scanu_join_cfm_handler(), and scanu_start_req_handler().

__INLINE struct ke_msg* ke_param2msg | ( | void const * | param_ptr | ) | `[read]`

Convert a parameter pointer to a message pointer.

Parameters:

  `[in]` | param_ptr | Pointer to the parameter member of a ke_msg Usually retrieved by a ke_msg_alloc()

Returns:
  The pointer to the ke_msg

Definition at line 114 of file ke_msg.h.

References ke_msg::param.

Referenced by apm_bss_config_push(), bfr_group_update_cfm(), mm_bcn_updated(), mm_scan_channel_end_ind_handler(), mm_tim_update_proceed(), and sm_bss_config_push().