Generic MAC Driver. More...

Collaboration diagram for MAC Driver:

Detailed Description

Generic MAC Driver.

This module implements a generic MAC (Media Access Control) driver for Ethernet controllers.

Precondition: In order to use the MAC driver the HAL_USE_MAC option must be enabled in halconf.h.

Macros
#define	MAC_SUPPORTS_ZERO_COPY TRUE
	This implementation supports the zero-copy mode API. More...

MAC configuration options
#define	MAC_USE_ZERO_COPY FALSE
	Enables an event sources for incoming packets. More...

#define	MAC_USE_EVENTS TRUE
	Enables an event sources for incoming packets. More...

Macro Functions
#define	macGetReceiveEventSource(macp) (&(macp)->rdevent)
	Enables the zero-copy API. More...

#define	macWriteTransmitDescriptor(tdp, buf, size) mac_lld_write_transmit_descriptor(tdp, buf, size)
	Writes to a transmit descriptor's stream. More...

#define	macReadReceiveDescriptor(rdp, buf, size) mac_lld_read_receive_descriptor(rdp, buf, size)
	Reads from a receive descriptor's stream. More...

#define	macGetNextTransmitBuffer(tdp, size, sizep) mac_lld_get_next_transmit_buffer(tdp, size, sizep)
	Returns a pointer to the next transmit buffer in the descriptor chain. More...

#define	macGetNextReceiveBuffer(rdp, sizep) mac_lld_get_next_receive_buffer(rdp, sizep)
	Returns a pointer to the next receive buffer in the descriptor chain. More...

PLATFORM configuration options
#define	PLATFORM_MAC_USE_MAC1 FALSE
	MAC driver enable switch. More...

Typedefs
typedef struct MACDriver	MACDriver
	Type of a structure representing a MAC driver. More...

Data Structures
struct	MACConfig
	Driver configuration structure. More...

struct	MACDriver
	Structure representing a MAC driver. More...

struct	MACTransmitDescriptor
	Structure representing a transmit descriptor. More...

struct	MACReceiveDescriptor
	Structure representing a receive descriptor. More...

Functions
void	macInit (void)
	MAC Driver initialization. More...

void	macObjectInit (MACDriver *macp)
	Initialize the standard part of a `MACDriver` structure. More...

void	macStart (MACDriver macp, const MACConfig config)
	Configures and activates the MAC peripheral. More...

void	macStop (MACDriver *macp)
	Deactivates the MAC peripheral. More...

msg_t	macWaitTransmitDescriptor (MACDriver macp, MACTransmitDescriptor tdp, sysinterval_t timeout)
	Allocates a transmission descriptor. More...

void	macReleaseTransmitDescriptor (MACTransmitDescriptor *tdp)
	Releases a transmit descriptor and starts the transmission of the enqueued data as a single frame. More...

msg_t	macWaitReceiveDescriptor (MACDriver macp, MACReceiveDescriptor rdp, sysinterval_t timeout)
	Waits for a received frame. More...

void	macReleaseReceiveDescriptor (MACReceiveDescriptor *rdp)
	Releases a receive descriptor. More...

bool	macPollLinkStatus (MACDriver *macp)
	Updates and returns the link status. More...

void	mac_lld_init (void)
	Low level MAC initialization. More...

void	mac_lld_start (MACDriver *macp)
	Configures and activates the MAC peripheral. More...

void	mac_lld_stop (MACDriver *macp)
	Deactivates the MAC peripheral. More...

msg_t	mac_lld_get_transmit_descriptor (MACDriver macp, MACTransmitDescriptor tdp)
	Returns a transmission descriptor. More...

void	mac_lld_release_transmit_descriptor (MACTransmitDescriptor *tdp)
	Releases a transmit descriptor and starts the transmission of the enqueued data as a single frame. More...

msg_t	mac_lld_get_receive_descriptor (MACDriver macp, MACReceiveDescriptor rdp)
	Returns a receive descriptor. More...

void	mac_lld_release_receive_descriptor (MACReceiveDescriptor *rdp)
	Releases a receive descriptor. More...

bool	mac_lld_poll_link_status (MACDriver *macp)
	Updates and returns the link status. More...

size_t	mac_lld_write_transmit_descriptor (MACTransmitDescriptor tdp, uint8_t buf, size_t size)
	Writes to a transmit descriptor's stream. More...

size_t	mac_lld_read_receive_descriptor (MACReceiveDescriptor rdp, uint8_t buf, size_t size)
	Reads from a receive descriptor's stream. More...

uint8_t *	mac_lld_get_next_transmit_buffer (MACTransmitDescriptor tdp, size_t size, size_t sizep)
	Returns a pointer to the next transmit buffer in the descriptor chain. More...

const uint8_t *	mac_lld_get_next_receive_buffer (MACReceiveDescriptor rdp, size_t sizep)
	Returns a pointer to the next receive buffer in the descriptor chain. More...

Enumerations

Variables
MACDriver	ETHD1
	MAC1 driver identifier. More...

Macro Definition Documentation

#define MAC_USE_ZERO_COPY FALSE

Enables an event sources for incoming packets.

Definition at line 45 of file hal_mac.h.

#define MAC_USE_EVENTS TRUE

Enables an event sources for incoming packets.

Definition at line 52 of file hal_mac.h.

#define macGetReceiveEventSource ( macp ) (&(macp)->rdevent)

Enables the zero-copy API.

Parameters

[in] macp pointer to the MACDriver object

Returns: The pointer to the EventSource structure.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 97 of file hal_mac.h.

#define macWriteTransmitDescriptor	(	tdp,
		buf,
		size
	)	mac_lld_write_transmit_descriptor(tdp, buf, size)

Writes to a transmit descriptor's stream.

Parameters

[in]	tdp	pointer to a `MACTransmitDescriptor` structure
[in]	buf	pointer to the buffer containing the data to be written
[in]	size	number of bytes to be written

Returns: The number of bytes written into the descriptor's stream, this value can be less than the amount specified in the parameter size if the maximum frame size is reached.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 113 of file hal_mac.h.

#define macReadReceiveDescriptor	(	rdp,
		buf,
		size
	)	mac_lld_read_receive_descriptor(rdp, buf, size)

Reads from a receive descriptor's stream.

Parameters

[in]	rdp	pointer to a `MACReceiveDescriptor` structure
[in]	buf	pointer to the buffer that will receive the read data
[in]	size	number of bytes to be read

Returns: The number of bytes read from the descriptor's stream, this value can be less than the amount specified in the parameter size if there are no more bytes to read.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 128 of file hal_mac.h.

#define macGetNextTransmitBuffer	(	tdp,
		size,
		sizep
	)	mac_lld_get_next_transmit_buffer(tdp, size, sizep)

Returns a pointer to the next transmit buffer in the descriptor chain.

Note: The API guarantees that enough buffers can be requested to fill a whole frame.

Parameters

[in]	tdp	pointer to a `MACTransmitDescriptor` structure
[in]	size	size of the requested buffer. Specify the frame size on the first call then scale the value down subtracting the amount of data already copied into the previous buffers.
[out]	sizep	pointer to variable receiving the real buffer size. The returned value can be less than the amount requested, this means that more buffers must be requested in order to fill the frame data entirely.

Returns: Pointer to the returned buffer.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 151 of file hal_mac.h.

#define macGetNextReceiveBuffer	(	rdp,
		sizep
	)	mac_lld_get_next_receive_buffer(rdp, sizep)

Returns a pointer to the next receive buffer in the descriptor chain.

Note: The API guarantees that the descriptor chain contains a whole frame.

Parameters

[in]	rdp	pointer to a `MACReceiveDescriptor` structure
[out]	sizep	pointer to variable receiving the buffer size, it is zero when the last buffer has already been returned.

Returns: Pointer to the returned buffer.

Return values

NULL	if the buffer chain has been entirely scanned.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 168 of file hal_mac.h.

#define MAC_SUPPORTS_ZERO_COPY TRUE

This implementation supports the zero-copy mode API.

Definition at line 37 of file hal_mac_lld.h.

#define PLATFORM_MAC_USE_MAC1 FALSE

MAC driver enable switch.

If set to TRUE the support for MAC1 is included.

Note: The default is FALSE.

Definition at line 53 of file hal_mac_lld.h.

Typedef Documentation

typedef struct MACDriver MACDriver

Type of a structure representing a MAC driver.

Definition at line 76 of file hal_mac.h.

Enumeration Type Documentation

enum macstate_t

Driver state machine possible states.

Enumerator
MAC_UNINIT	Not initialized.
MAC_STOP	Stopped.
MAC_ACTIVE	Active.

Definition at line 67 of file hal_mac.h.

Function Documentation

void macInit ( void )

MAC Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 64 of file hal_mac.c.

References mac_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void macObjectInit ( MACDriver * macp )

Initialize the standard part of a MACDriver structure.

Parameters

[out] macp pointer to the MACDriver object

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 76 of file hal_mac.c.

References MACDriver::config, MAC_STOP, osalEventObjectInit(), osalThreadQueueObjectInit(), MACDriver::rdevent, MACDriver::rdqueue, MACDriver::state, and MACDriver::tdqueue.

Referenced by mac_lld_init().

Here is the call graph for this function:

void macStart	(	MACDriver *	macp,
		const MACConfig *	config
	)

Configures and activates the MAC peripheral.

Parameters

[in]	macp	pointer to the `MACDriver` object
[in]	config	pointer to the `MACConfig` object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 95 of file hal_mac.c.

References MACDriver::config, MAC_ACTIVE, mac_lld_start(), MAC_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and MACDriver::state.

Here is the call graph for this function:

void macStop ( MACDriver * macp )

Deactivates the MAC peripheral.

Parameters

[in] macp pointer to the MACDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 115 of file hal_mac.c.

References MACDriver::config, MAC_ACTIVE, mac_lld_stop(), MAC_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and MACDriver::state.

Here is the call graph for this function:

msg_t macWaitTransmitDescriptor	(	MACDriver *	macp,
		MACTransmitDescriptor *	tdp,
		sysinterval_t	timeout
	)

Allocates a transmission descriptor.

One of the available transmission descriptors is locked and returned. If a descriptor is not currently available then the invoking thread is queued until one is freed.

Parameters

[in]	macp	pointer to the `MACDriver` object
[out]	tdp	pointer to a `MACTransmitDescriptor` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	the descriptor was obtained.
MSG_TIMEOUT	the operation timed out, descriptor not initialized.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 150 of file hal_mac.c.

References MAC_ACTIVE, mac_lld_get_transmit_descriptor(), osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadEnqueueTimeoutS(), MACDriver::state, and MACDriver::tdqueue.

Here is the call graph for this function:

void macReleaseTransmitDescriptor ( MACTransmitDescriptor * tdp )

Releases a transmit descriptor and starts the transmission of the enqueued data as a single frame.

Parameters

[in] tdp the pointer to the MACTransmitDescriptor structure

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 179 of file hal_mac.c.

References mac_lld_release_transmit_descriptor(), and osalDbgCheck.

Here is the call graph for this function:

msg_t macWaitReceiveDescriptor	(	MACDriver *	macp,
		MACReceiveDescriptor *	rdp,
		sysinterval_t	timeout
	)

Waits for a received frame.

Stops until a frame is received and buffered. If a frame is not immediately available then the invoking thread is queued until one is received.

Parameters

[in]	macp	pointer to the `MACDriver` object
[out]	rdp	pointer to a `MACReceiveDescriptor` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: The operation status.

Return values

MSG_OK	the descriptor was obtained.
MSG_TIMEOUT	the operation timed out, descriptor not initialized.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 205 of file hal_mac.c.

References MAC_ACTIVE, mac_lld_get_receive_descriptor(), osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadEnqueueTimeoutS(), MACDriver::rdqueue, and MACDriver::state.

Here is the call graph for this function:

void macReleaseReceiveDescriptor ( MACReceiveDescriptor * rdp )

Releases a receive descriptor.

The descriptor and its buffer are made available for more incoming frames.

Parameters

[in] rdp the pointer to the MACReceiveDescriptor structure

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 234 of file hal_mac.c.

References mac_lld_release_receive_descriptor(), and osalDbgCheck.

Here is the call graph for this function:

bool macPollLinkStatus ( MACDriver * macp )

Updates and returns the link status.

Parameters

[in] macp pointer to the MACDriver object

Returns: The link status.

Return values

true	if the link is active.
false	if the link is down.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 251 of file hal_mac.c.

References MAC_ACTIVE, mac_lld_poll_link_status(), osalDbgAssert, osalDbgCheck, and MACDriver::state.

Here is the call graph for this function:

void mac_lld_init ( void )

Low level MAC initialization.

Function Class:Not an API, this function is for internal use only.

Definition at line 69 of file hal_mac_lld.c.

References macObjectInit().

Referenced by macInit().

Here is the call graph for this function:

void mac_lld_start ( MACDriver * macp )

Configures and activates the MAC peripheral.

Parameters

[in] macp pointer to the MACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 84 of file hal_mac_lld.c.

References MAC_STOP, and MACDriver::state.

Referenced by macStart().

void mac_lld_stop ( MACDriver * macp )

Deactivates the MAC peripheral.

Parameters

[in] macp pointer to the MACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 105 of file hal_mac_lld.c.

References MAC_STOP, and MACDriver::state.

Referenced by macStop().

msg_t mac_lld_get_transmit_descriptor	(	MACDriver *	macp,
		MACTransmitDescriptor *	tdp
	)

Returns a transmission descriptor.

One of the available transmission descriptors is locked and returned.

Parameters

[in]	macp	pointer to the `MACDriver` object
[out]	tdp	pointer to a `MACTransmitDescriptor` structure

Returns: The operation status.

Return values

MSG_OK	the descriptor has been obtained.
MSG_TIMEOUT	descriptor not available.

Function Class:Not an API, this function is for internal use only.

Definition at line 132 of file hal_mac_lld.c.

Referenced by macWaitTransmitDescriptor().

void mac_lld_release_transmit_descriptor ( MACTransmitDescriptor * tdp )

Releases a transmit descriptor and starts the transmission of the enqueued data as a single frame.

Parameters

[in] tdp the pointer to the MACTransmitDescriptor structure

Function Class:Not an API, this function is for internal use only.

Definition at line 149 of file hal_mac_lld.c.

Referenced by macReleaseTransmitDescriptor().

msg_t mac_lld_get_receive_descriptor	(	MACDriver *	macp,
		MACReceiveDescriptor *	rdp
	)

Returns a receive descriptor.

Parameters

[in]	macp	pointer to the `MACDriver` object
[out]	rdp	pointer to a `MACReceiveDescriptor` structure

Returns: The operation status.

Return values

MSG_OK	the descriptor has been obtained.
MSG_TIMEOUT	descriptor not available.

Function Class:Not an API, this function is for internal use only.

Definition at line 166 of file hal_mac_lld.c.

Referenced by macWaitReceiveDescriptor().

void mac_lld_release_receive_descriptor ( MACReceiveDescriptor * rdp )

Releases a receive descriptor.

The descriptor and its buffer are made available for more incoming frames.

Parameters

[in] rdp the pointer to the MACReceiveDescriptor structure

Function Class:Not an API, this function is for internal use only.

Definition at line 184 of file hal_mac_lld.c.

Referenced by macReleaseReceiveDescriptor().

bool mac_lld_poll_link_status ( MACDriver * macp )

Updates and returns the link status.

Parameters

[in] macp pointer to the MACDriver object

Returns: The link status.

Return values

true	if the link is active.
false	if the link is down.

Function Class:Not an API, this function is for internal use only.

Definition at line 200 of file hal_mac_lld.c.

Referenced by macPollLinkStatus().

size_t mac_lld_write_transmit_descriptor	(	MACTransmitDescriptor *	tdp,
		uint8_t *	buf,
		size_t	size
	)

Writes to a transmit descriptor's stream.

Parameters

[in]	tdp	pointer to a `MACTransmitDescriptor` structure
[in]	buf	pointer to the buffer containing the data to be written
[in]	size	number of bytes to be written

Returns: The number of bytes written into the descriptor's stream, this value can be less than the amount specified in the parameter size if the maximum frame size is reached.

Function Class:Not an API, this function is for internal use only.

Definition at line 221 of file hal_mac_lld.c.

size_t mac_lld_read_receive_descriptor	(	MACReceiveDescriptor *	rdp,
		uint8_t *	buf,
		size_t	size
	)

Reads from a receive descriptor's stream.

Parameters

[in]	rdp	pointer to a `MACReceiveDescriptor` structure
[in]	buf	pointer to the buffer that will receive the read data
[in]	size	number of bytes to be read

Returns: The number of bytes read from the descriptor's stream, this value can be less than the amount specified in the parameter size if there are no more bytes to read.

Function Class:Not an API, this function is for internal use only.

Definition at line 244 of file hal_mac_lld.c.

uint8_t * mac_lld_get_next_transmit_buffer	(	MACTransmitDescriptor *	tdp,
		size_t	size,
		size_t *	sizep
	)

Returns a pointer to the next transmit buffer in the descriptor chain.

Note: The API guarantees that enough buffers can be requested to fill a whole frame.

Parameters

[in]	tdp	pointer to a `MACTransmitDescriptor` structure
[in]	size	size of the requested buffer. Specify the frame size on the first call then scale the value down subtracting the amount of data already copied into the previous buffers.
[out]	sizep	pointer to variable receiving the buffer size, it is zero when the last buffer has already been returned. Note that a returned size lower than the amount requested means that more buffers must be requested in order to fill the frame data entirely.

Returns: Pointer to the returned buffer.

Return values

NULL	if the buffer chain has been entirely scanned.

Function Class:Not an API, this function is for internal use only.

Definition at line 276 of file hal_mac_lld.c.

const uint8_t * mac_lld_get_next_receive_buffer	(	MACReceiveDescriptor *	rdp,
		size_t *	sizep
	)

Returns a pointer to the next receive buffer in the descriptor chain.

Note: The API guarantees that the descriptor chain contains a whole frame.

Parameters

[in]	rdp	pointer to a `MACReceiveDescriptor` structure
[out]	sizep	pointer to variable receiving the buffer size, it is zero when the last buffer has already been returned.

Returns: Pointer to the returned buffer.

Return values

NULL	if the buffer chain has been entirely scanned.

Function Class:Not an API, this function is for internal use only.

Definition at line 301 of file hal_mac_lld.c.

Variable Documentation

MACDriver ETHD1

MAC1 driver identifier.

Definition at line 45 of file hal_mac_lld.c.

Detailed Description

Macros

MAC configuration options

Macro Functions

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation