# ICOM module documentation

## Overview

ICOM (Internal Communication) is a simple C language internal communication module, which is used to realize efficient bidirectional data communication in embedded systems. It provides a communication mechanism based on shared memory to support multi-channel data transmission and state management.

## Core features

- **Bidirectional communication** : Support for separate send and receive channels
- **State management** : Provides four channel states: initialized, idle, busy, and error
- **Data length control** : Supports dynamic data length setting and validation
- **Live detection** : Automatically detects the online state of the communication peer
- **Cache control** : Supports cache invalidation and writeback operations
- **Multi-channel support** : Multiple send and receive channels can be configured

## Architectural Design

### Communication protocol format
| offset | field | size | description |
| :----: | :--: | :--: | :--------- |
| 0 | Flag | 4 | Channel status flag |
| 4 | Tcnt | 4 | Send channel count |
| 8 | Rcnt | 4 | Receive channel count |
| 12 | Dlen | 4 | data length |
| 16 | Data | N | actual data |

### State Machine design

- **INIT** : The initial state
- **BUSY** : Busy (in data transfer)
- **IDLE** : Idle state (transferable)
- **ERROR** : An error state

## API explained in detail

### Initialization functions
```c
int icom_init(ICOM *icom);
```
Initialize the ICOM module and configure the sending and receiving channels.

### Task handlers
```c
int icom_task(ICOM *icom);
```
Handle the periodic tasks of the ICOM module, including online state detection and data reception processing.

### Data sending function
```c
int icom_transmit(ICOM *icom, uint16_t channel, uint8_t *data, uint32_t length);
```
Send data over the specified channel.

### Data receiving functions
```c
int icom_receive(ICOM *icom, uint16_t channel, uint8_t *data, uint32_t *length);
```
Handle the periodic tasks of the ICOM module, including online state detection and data reception processing. Receives data from the specified channel.

### Online presence checks
```c
int icom_txchannel_online(ICOM *icom, uint16_t channel, uint8_t *online);
int icom_rxchannel_online(ICOM *icom, uint16_t channel, uint8_t *online);
```
Check the online status of the send/receive channel.

## Instructions

1. Initialize the ICOM struct and configure the channel
2. Call icom_init() for initialization
3. Periodic calls to icom_task() for state management and data reception processing
4. Use icom_transmit() to send data
5. Use icom_receive() to receive data

## Advanced features

* Manual receive mode: You can manually check the receive status without using callbacks
* Cache control: Cache control via 'inv' and 'wbinv' callbacks
* Private data: Each channel maintains 4 private data words for extended functionality

## Use cases

* Inter-Processor Communication (IPC)
* Data exchange between multiple cores
* Modular system component communication
* Embedded systems that require shared memory communication