Local Symmetric Data-link. Implements an extremely simple protocol to link two full-duplex devices, multiplexing the data link. More...

Macros
#define	LSD_OVERHEAD 4
	LSD frame overhead in bytes.
#define	LSD_MAX_CH 4
	Maximum number of available simultaneous channels.
#define	LSD_MAX_LEN 4095
	Maximum data payload length.
#define	LSD_BUF_FRAMES 2
	Number of buffer frames available.

Typedefs
typedef void(*	lsd_send_cb) (enum lsd_status stat, void *ctx)
	Callback for the asynchronous lsd_send() function.
typedef void(*	lsd_recv_cb) (enum lsd_status stat, uint8_t ch, char data, uint16_t len, void ctx)
	Callback for the asynchronous lsd_recv() function.

Enumerations
enum	lsd_status { LSD_STAT_ERR_FRAMING = -5 , LSD_STAT_ERR_INVALID_CH = -4 , LSD_STAT_ERR_FRAME_TOO_LONG = -3 , LSD_STAT_ERR_IN_PROGRESS = -2 , LSD_STAT_ERROR = -1 , LSD_STAT_COMPLETE = 0 , LSD_STAT_BUSY = 1 }
	Return status codes for LSD functions. More...

Functions
void	lsd_init (void)
	Module initialization.
int	lsd_ch_enable (uint8_t ch)
	Enables a channel to start reception and be able to send data.
int	lsd_ch_disable (uint8_t ch)
	Disables a channel to stop reception and prohibit sending data.
enum lsd_status	lsd_send (uint8_t ch, const char data, int16_t len, void ctx, lsd_send_cb send_cb)
	Asynchronously sends data through a previously enabled channel.
enum lsd_status	lsd_send_sync (uint8_t ch, const char *data, int16_t len)
	Synchronously sends data through a previously enabled channel.
enum lsd_status	lsd_recv (char buf, int16_t len, void ctx, lsd_recv_cb recv_cb)
	Asyncrhonously Receives a frame using LSD protocol.
enum lsd_status	lsd_recv_sync (char buf, uint16_t len, uint8_t *ch)
	Syncrhonously Receives a frame using LSD protocol.
void	lsd_process (void)
	Processes sends/receives pending data.
void	lsd_line_sync (void)
	Sends syncrhonization frame.

Detailed Description

Local Symmetric Data-link. Implements an extremely simple protocol to link two full-duplex devices, multiplexing the data link.

The multiplexing facility allows having up to LSD_MAX_CH simultaneous channels on the serial link.

The module has synchronous functions to send/receive data (easy to use, but due to polling hang the console until transfer is complete) and their asyncronous counterparts. The asynchronous functions return immediately, but require calling frequently lsd_process() to actually send/receive data. Once the asynchronous functions complete sending/receiving data, the specified callback is run.

Author: Jesus Alonso (doragasu); Juan Antonio (PaCHoN)

Date: 2019~2025

Note: Unfortunately the Megadrive does have neither an interrupt pin nor DMA threshold pins in the cartridge slot, so polling is the only way. So you have Megadrive does not have an interrupt pin on the cart, implementing more efficient data transmission techniques will be tricky.

Warning

The syncrhonous API is easier to use, but a lot less reliable:

It polls, using all the CPU until the send/recv operation completes.
A lsd_recv_sync() can freeze the machine if no frame is received. USE IT WITH CARE!

Enumeration Type Documentation

◆ lsd_status

enum lsd_status

Return status codes for LSD functions.

Enumerator
LSD_STAT_ERR_FRAMING	Frame format error.
LSD_STAT_ERR_INVALID_CH	Invalid channel.
LSD_STAT_ERR_FRAME_TOO_LONG	Frame is too long.
LSD_STAT_ERR_IN_PROGRESS	Operation in progress.
LSD_STAT_ERROR	General error.
LSD_STAT_COMPLETE	No error.
LSD_STAT_BUSY	Doing requested operation.

Function Documentation

◆ lsd_ch_disable()

int lsd_ch_disable ( uint8_t ch )

Disables a channel to stop reception and prohibit sending data.

Parameters

[in] ch Channel number.

Returns: LSD_OK on success, LSD_ERROR otherwise.

◆ lsd_ch_enable()

int lsd_ch_enable ( uint8_t ch )

Enables a channel to start reception and be able to send data.

Parameters

[in] ch Channel number.

Returns: LSD_OK on success, LSD_ERROR otherwise.

◆ lsd_line_sync()

void lsd_line_sync ( void )

Sends syncrhonization frame.

This function sends a chunk of 0x55 bytes to help physical layer to synchronize. It is usually not necessary to use this function, but might help some UART chips to compute an accurate clock.

◆ lsd_process()

void lsd_process ( void )

Processes sends/receives pending data.

Call this function as much as possible when using the asynchronous lsd_send() and lsd_receive() functions.

◆ lsd_recv()

enum lsd_status lsd_recv	(	char *	buf,
		int16_t	len,
		void *	ctx,
		lsd_recv_cb	recv_cb )

Asyncrhonously Receives a frame using LSD protocol.

Parameters

[in]	buf	Buffer for reception.
[in]	len	Buffer length.
[in]	ctx	Context for the receive callback function.
[in]	recv_cb	Callback to run when receive completes or errors.

Returns: Status of the receive procedure.

◆ lsd_recv_sync()

enum lsd_status lsd_recv_sync	(	char *	buf,
		uint16_t *	len,
		uint8_t *	ch )

Syncrhonously Receives a frame using LSD protocol.

Parameters

[out]	buf	Buffer for received data.
[in,out]	len	On input: buffer length. On output: received frame length.
[out]	ch	Channel on which the data has been received.

Warning: This function polls until the reception is complete, or a reception error occurs.; If no frame is received when this function is called, the machine will lock.

◆ lsd_send()

enum lsd_status lsd_send	(	uint8_t	ch,
		const char *	data,
		int16_t	len,
		void *	ctx,
		lsd_send_cb	send_cb )

Asynchronously sends data through a previously enabled channel.

Parameters

[in]	ch	Channel number to use.
[in]	data	Buffer to send.
[in]	len	Length of the buffer to send.
[in]	ctx	Context for the send callback function.
[in]	send_cb	Callback to run when send completes or errors.

Returns: Status of the send procedure. Usually LSD_STAT_BUSY is returned, and the send procedure is then performed in background.

Note: Calling this function while there is a send procedure in progress, will cause the function call to fail with LSD_STAT_SEND_ERR_IN_PROGRESS.

◆ lsd_send_sync()

enum lsd_status lsd_send_sync	(	uint8_t	ch,
		const char *	data,
		int16_t	len )

Synchronously sends data through a previously enabled channel.

Parameters

[in]	ch	Channel number to use.
[in]	data	Buffer to send.
[in]	len	Length of the buffer to send.

Returns: Status of the send procedure.

Warning: This function polls until the procedure is complete (or errors).

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ lsd_status

Function Documentation

◆ lsd_ch_disable()

◆ lsd_ch_enable()

◆ lsd_line_sync()

◆ lsd_process()

◆ lsd_recv()

◆ lsd_recv_sync()

◆ lsd_send()

◆ lsd_send_sync()