# MACIF
[MACSW]

This define the interface used by MAC software to communicate with the controlling layer. More...

Collaboration diagram for MACIF:

## Functions
int | macif_init (void)
| Initialize the MAC interface.
int | macif_kmsg_push (int msg_id, int task_id, void *param, int param_len)
| Push a kmsg from the control layer to the wifi stack.
void | macif_msg_evt (int dummy)
| Kernel event handler for the handling of messages pushed by control layer.
void | macif_kmsg_fwd (const struct ke_msg *ke_msg)
| Forward a kernel message to the MAC interface.
void | macif_prim_tbtt_ind (void)
| Indicate control layer that the primary TBTT is pending.
void | macif_sec_tbtt_ind (void)
| Indicate control layer that the secondary TBTT is pending.
void | macif_rx_data_ind (void)
| Signal to the upper layers the presence of data in the host RX buffers.
uint8_t | macif_rx_get_packet_threshold (void)
| Get the number of received packets above which the host shall be warned.
bool | macif_rx_buf_check (void)
| Checks if a host buffer is currently available.
uint32_t | macif_rx_buf_get (uint32_t *host_id)
| Retrieve a RX host buffer address for future DMA transfer.
void | macif_rx_buf_ind (void)
| Indicate to the lower layers that a buffer has just been pushed.
void | macif_rx_desc_upload (struct co_list *desc_list)
| Upload the list of prepared RX status descriptors to upper layers.
void | macif_tx_data_ind (int queue_idx)
| Signal to the lower layers the presence of data in the TX queue passed as parameter.
void | macif_tx_evt (int queue_idx)
| Kernel event handler for the handling of the TX descriptor pushed by the upper layers.
bool | macif_tx_q_has_data (int queue_idx)
| Get the status of the TX queue.
uint8_t | macif_tx_q_len (int queue_idx, int vif_idx)
| Check how many tx descriptors are available on the requested queue for a VIF.
uint32_t | macif_tx_pattern_addr_get (void)
| Get the host address of the TX payload descriptor pattern It is not used in fully hosted partitioning.
uint32_t | macif_buffered_get (uint8_t sta, uint8_t tid)
| Get the buffered data for a given sta/tid.
void | macif_tx_enable_users (int queue_idx, uint8_t active_users)
| Re-enable the user queues that were disabled.
void | macif_tx_cfm_start (uint8_t access_category)
| Initialize a new TX confirmation upload process.
void | macif_tx_cfm_push (uint8_t access_category, struct txdesc *txdesc)
| Push a TX confirmation for upload to upper layers.
void | macif_tx_cfm_done (uint8_t access_category, bool poll)
| Program the pending confirmation for upload.
void | macif_tx_cfm_dma_int_handler (void)
| Handler for DMA transfer of confirmations.

## Detailed Description

This define the interface used by MAC software to communicate with the controlling layer.

Several implementation of this interface are available depending if MAC software is controlled locally or from a remote CPU.

## Function Documentation

uint32_t macif_buffered_get | ( | uint8_t | sta,
|  | uint8_t | tid |
| ) |  |  |

Get the buffered data for a given sta/tid.

Parameters:

  `[in]` | sta | STA index
  `[in]` | tid | TID

Returns:
  number of bytes buffered

Definition at line 302 of file macif_ipc.c.

References ipc_emb_buffered_get().

int macif_init | ( | void |  | ) |

Initialize the MAC interface.

Returns:
  0 if success and !=0 is an error occurred

Definition at line 111 of file macif_ipc.c.

References CFM_IDX_MSK, co_list_push_back(), CPU2HW, macif_tx_cfm_tag::in_idx, IPC_DMA_LLI_CFM_TX, macif_tx_cfm_tag::lli_cnt, macif_ipc_env, sizeof_b, macif_ipc_env_tag::tx_cfm, and UNSUP_RX_VECT_MAX.

void macif_kmsg_fwd | ( | const struct ke_msg * | ke_msg | ) |

Forward a kernel message to the MAC interface.

Parameters:

  `[in]` | ke_msg | Pointer on the message

Definition at line 151 of file macif_ipc.c.

References ipc_emb_kmsg_fwd().

int macif_kmsg_push | ( | int | msg_id,
|  | int | task_id,
|  | void * | param,
|  | int | param_len |
| ) |  |  |

Push a kmsg from the control layer to the wifi stack.

Memory pointed by `param` will be copied into a Kmsg for the wifi task, it can then be re-used after the call of this function. May not be needed if control layer is using KE_EVT_MACIF_MSG_BIT to indicate new message to wifi stack.

Parameters:

  `[in]` | msg_id | Message id.
  `[in]` | task_id | Id of the Wifi sub task destination.
  `[in]` | param | Pointer to message parameters
  `[in]` | param_len | Size, in bytes, on the `param` buffer

Returns:
  -1 allocation for message failed and 0 otherwise.

void macif_msg_evt | ( | int | dummy | ) |

Kernel event handler for the handling of messages pushed by control layer.

This is wifi task's handler for KE_EVT_MACIF_MSG_BIT. It is assumed that control layer provides msg address by other means (e.g. by using a global variable). May not be needed if control layer is using macif_kmsg_push to send message to wifi stack.

Parameters:

  `[in]` | dummy | Parameter not used but required to follow the kernel event callback format

Definition at line 146 of file macif_ipc.c.

References ipc_emb_msg_evt().

void macif_prim_tbtt_ind | ( | void |  | ) |

Indicate control layer that the primary TBTT is pending.

Definition at line 156 of file macif_ipc.c.

References ipc_emb_prim_tbtt_ind().

bool macif_rx_buf_check | ( | void |  | ) |

Checks if a host buffer is currently available.

Returns:
  true if a buffer is available, false otherwise.

Definition at line 176 of file macif_ipc.c.

References ipc_emb_hostrxbuf_check().

uint32_t macif_rx_buf_get | ( | uint32_t * | host_id | ) |

Retrieve a RX host buffer address for future DMA transfer.

It just returns the pointer values set by the upper layers at init time and after each reception. The buffer is not available anymore after the call. Prior to the call to this function, a call to macif_rx_buf_check has to be performed to ensure that there is a buffer available.

Parameters:

  `[out]` | host_id | HostId linked to the buffer

Returns:
  Hostbuf address.

Definition at line 182 of file macif_ipc.c.

References ipc_emb_hostrxbuf_get().

Referenced by rxl_mpdu_transfer().

void macif_rx_buf_ind | ( | void |  | ) |

Indicate to the lower layers that a buffer has just been pushed.

In case the RX flow control was activated, the WiFi task will be awaken in order to resume the RX processing.

void macif_rx_data_ind | ( | void |  | ) |

Signal to the upper layers the presence of data in the host RX buffers.

This function typically triggers an interrupt to the host CPU. It is not used in fully hosted partitioning.

Definition at line 171 of file macif_ipc.c.

References ipc_emb_rxdata_ind().

void macif_rx_desc_upload | ( | struct co_list * | desc_list | ) |

Upload the list of prepared RX status descriptors to upper layers.

Parameters:

  `[in]` | desc_list | Pointer to the list of RX status descriptors

Definition at line 194 of file macif_ipc.c.

References co_list_pick(), co_list_pop_front(), CPU2HW, dma_desc::dest, rxu_stat_desc::dma_desc, dma_push(), ipc_emb_hostrxdesc_check(), ipc_emb_hostrxdesc_get(), dma_desc::next, PROF_IPCDESC_TRANSFER_CLR, PROF_IPCDESC_TRANSFER_SET, RX_DATA_UPLOAD_CHAN, rxl_upload_cntrl_push_pending(), and rxu_stat_desc::upload_cntrl.

Referenced by rxu_cntrl_defrag_timeout_cb(), rxu_cntrl_reord_bar_check(), and rxu_cntrl_reord_timeout_cb().

uint8_t macif_rx_get_packet_threshold | ( | void |  | ) |

Get the number of received packets above which the host shall be warned.

Returns:
  The RX packet threshold

Definition at line 166 of file macif_ipc.c.

References IPC_RXBUF_CNT.

Referenced by rxl_cntrl_init().

void macif_sec_tbtt_ind | ( | void |  | ) |

Indicate control layer that the secondary TBTT is pending.

Definition at line 161 of file macif_ipc.c.

References ipc_emb_sec_tbtt_ind().

void macif_tx_cfm_dma_int_handler | ( | void |  | ) |

Handler for DMA transfer of confirmations.

Definition at line 446 of file macif_ipc.c.

References CFM_IDX_MSK, IPC_DMA_LLI_CFM_MASK, ipc_emb_txcfm_ind(), macif_tx_cfm_tag::lli_cnt, macif_ipc_env, macif_tx_cfm_lli_done(), ps_env_tag::prevent_sleep, PROF_TX_CFM_DMA_IRQ_CLR, PROF_TX_CFM_DMA_IRQ_SET, ps_env, PS_TX_CFM_UPLOADING, macif_ipc_env_tag::tx_cfm, and macif_tx_cfm_tag::user_cfm.

Referenced by macif_tx_cfm_done().

void macif_tx_cfm_done | ( | uint8_t | access_category,
|  | bool | poll |
| ) |  |  |

Program the pending confirmation for upload.

This function shall be called only after having first initialized a confirmation session using macif_tx_cfm_start

Parameters:

  `[in]` | access_category | Access category value
  `[in]` | poll | Flag indicating if the function shall not return (true) until all confirmations are uploaded

Definition at line 409 of file macif_ipc.c.

References ASSERT_ERR, CFM_IDX_MSK, macif_tx_cfm_tag::cfm_ind, CFM_LLICTRL, dma_desc::ctrl, macif_tx_cfm_tag::curr, dma_lli_poll(), dma_push(), macif_tx_cfm_tag::first, GLOBAL_INT_DISABLE, GLOBAL_INT_RESTORE, macif_tx_cfm_tag::in_idx, IPC_DMA_LLI_CFM_TX, macif_ipc_env, macif_tx_cfm_dma_int_handler(), ps_env_tag::prevent_sleep, ps_env, PS_TX_CFM_UPLOADING, RX_DATA_UPLOAD_CHAN, macif_ipc_env_tag::tx_cfm, and macif_tx_cfm_tag::user_cfm.

Referenced by macif_tx_cfm_push(), txl_cfm_evt(), txl_cfm_flush(), and txl_cfm_flush_desc().

void macif_tx_cfm_push | ( | uint8_t | access_category,
|  | struct txdesc * | txdesc |
| ) |  |  |

Push a TX confirmation for upload to upper layers.

Parameters:

  `[in]` | access_category | Access category for the confirmation
  `[in]` | txdesc | Pointer to the TX descriptor for which a CFM is pushed

Definition at line 352 of file macif_ipc.c.

References macif_tx_cfm_tag::cfm_cnt, CFM_CNT_THRESHOLD, macif_tx_cfm_tag::cfm_ind, CFM_STATUS_OFFSET, CO_BIT, CPU2HW, dma_desc::ctrl, macif_tx_cfm_tag::curr, dma_desc::dest, tx_hw_desc::dma_desc, macif_tx_cfm_tag::first, get_user_pos(), txdesc::host, lmacdesc::hw_desc, txdesc::lmac, macif_ipc_env, macif_tx_cfm_done(), dma_desc::next, hostdesc::packet_addr, txl_cntrl_env_tag::pck_cnt, RW_USER_MAX, hostdesc::status_desc_addr, macif_ipc_env_tag::tx_cfm, and txl_cntrl_env.

Referenced by txl_cfm_evt(), txl_cfm_flush(), and txl_cfm_flush_desc().

void macif_tx_cfm_start | ( | uint8_t | access_category | ) |

Initialize a new TX confirmation upload process.

This process shall be closed using macif_tx_cfm_done before starting a new session.

Parameters:

  `[in]` | access_category | Access category for the confirmations

Definition at line 340 of file macif_ipc.c.

References macif_tx_cfm_tag::cfm_cnt, macif_tx_cfm_tag::cfm_ind, CO_BIT, macif_tx_cfm_tag::curr, macif_tx_cfm_tag::first, macif_ipc_env, and macif_ipc_env_tag::tx_cfm.

Referenced by txl_cfm_evt(), txl_cfm_flush(), and txl_cfm_flush_desc().

void macif_tx_data_ind | ( | int | queue_idx | ) |

Signal to the lower layers the presence of data in the TX queue passed as parameter.

This function typically triggers an event in the WiFi stack. Used only in FullHost.

Parameters:

  `[in]` | queue_idx | Index of the queue in which data is available

void macif_tx_enable_users | ( | int | queue_idx,
|  | uint8_t | active_users |
| ) |  |  |

Re-enable the user queues that were disabled.

Parameters:

  `[in]` | queue_idx | Index of the TX queue
  `[in]` | active_users | Bit field showing the users to re-enable

Definition at line 308 of file macif_ipc.c.

References ipc_emb_enable_users().

void macif_tx_evt | ( | int | queue_idx | ) |

Kernel event handler for the handling of the TX descriptor pushed by the upper layers.

Parameters:

  `[in]` | queue_idx | Index of the TX queue for which the event is called

Definition at line 282 of file macif_ipc.c.

References ipc_emb_tx_evt().

uint32_t macif_tx_pattern_addr_get | ( | void |  | ) |

Get the host address of the TX payload descriptor pattern It is not used in fully hosted partitioning.

Returns:
  The address of the TX descriptor pattern

Definition at line 297 of file macif_ipc.c.

References ipc_emb_tx_pattern_addr_get().

Referenced by txl_int_fake_transfer().

bool macif_tx_q_has_data | ( | int | queue_idx | ) |

Get the status of the TX queue.

Parameters:

  `[in]` | queue_idx | Index of the TX queue for which the event is called

Returns:
  true if data is queued and false otherwise.

Definition at line 287 of file macif_ipc.c.

References ipc_emb_tx_q_has_data().

Referenced by mm_bcn_build(), and txl_frame_exchange_done().

uint8_t macif_tx_q_len | ( | int | queue_idx,
|  | int | vif_idx |
| ) |  |  |

Check how many tx descriptors are available on the requested queue for a VIF.

It is not used in fully hosted partitioning.

Parameters:

  `[in]` | queue_idx | Index of the TX queue
  `[in]` | vif_idx | Index of the Vif

Returns:
  Number of txdesc ready on the TX queue for the specified vif

Definition at line 292 of file macif_ipc.c.

References ipc_emb_tx_q_len().