enc28j60-struct.example.h File Reference

Part of enc28j60 driver. More...

#include <stdint.h>

Include dependency graph for enc28j60-struct.example.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	enc28j60
	Structure holding important informations about enc28j60 and about the latest transmission performed. More...

Macros
#define	ENC28J60_ERROR_TOO_MANY_COLLISIONS   -0x900
	Error code indicating that max number of retries were performed and we were still unable to transmit the frame. More...
#define	ENC28J60_ERROR_RX_TIMED_OUT   -0x901
	Error code indicating that we timed out while waiting for a packet in enc28j60_receiveframeblocking(). More...
#define	ENC28J60_TIMER_TICK_PER_SECOND   1000
	How many ticks are there per second. More...
#define	ENC28J60_CALC_REMAINING_TICKS(GOAL, CUR)   ((int16_t) (GOAL) - (int16_t) (CUR))
	Calculate how many ticks are remaining. More...

Typedefs
typedef uint16_t	enc28j60_tick
	TODO: Change it to uint32_t or uint8_t, depending on the timer resolution. More...

Functions
int	enc28j60_spi_advanced_transfer (enc28j60 *instance, const char *tx1, char *rx1, unsigned length1, const char *tx2, char *rx2, unsigned length2, enc28j60_spi_callback on_finish)
	This function performs (using DMA or blocking I/O) parallely transmision from 'tx1' buffer and reception into 'rx1' buffer (if 'rx1' is not null), and once this transmission is completed, performs transmission from 'tx2' (if not null) into 'rx2' (if not null). More...
int	enc28j60_spi_transfer_join (enc28j60 *instance)
	This function should wait until SPI operation in progress (if any) finishes and then return. More...
bool	enc28j60_spi_error_handler (enc28j60 *instance, int error_code, uint16_t retry)
	This function is called before callback when non-zero error code is received from enc28j60_spi_transfer() or enc28j60_spi_advanced_transfer(). More...
int	enc28j60_delay (enc28j60 *ins, enc28j60_tick ticks)
	Wait until given number of ticks passes. More...
int	enc28j60_getticks (enc28j60 *ins, enc28j60_tick *ticks)
	Get current number of ticks. More...

Detailed Description

Part of enc28j60 driver.

Author

Dalibor Drgon dalib.nosp@m.or.d.nosp@m.rgon@.nosp@m.gmai.nosp@m.l.com

Version

1.0

Date

2020-05-01

Copyright

Copyright (c) 2020 Dalibor Drgon dalib.nosp@m.or.d.nosp@m.rgon@.nosp@m.gmai.nosp@m.l.com This code is licensed under MIT license (see LICENSE.txt for details)

Macro Definition Documentation

ENC28J60_ERROR_TOO_MANY_COLLISIONS

#define ENC28J60_ERROR_TOO_MANY_COLLISIONS   -0x900

Error code indicating that max number of retries were performed and we were still unable to transmit the frame.

TODO: Change its value if such value for error code is already used.

ENC28J60_ERROR_RX_TIMED_OUT

#define ENC28J60_ERROR_RX_TIMED_OUT   -0x901

Error code indicating that we timed out while waiting for a packet in enc28j60_receiveframeblocking().

TODO: Change its value if such value for error code is already used.

ENC28J60_TIMER_TICK_PER_SECOND

#define ENC28J60_TIMER_TICK_PER_SECOND   1000

How many ticks are there per second.

NOTE: This should be at least 1 millisecond to quarantee best performance, but even for less precise timers than that the functionality is preserved.

ENC28J60_CALC_REMAINING_TICKS

#define ENC28J60_CALC_REMAINING_TICKS	(		GOAL,
			CUR
	)		((int16_t) (GOAL) - (int16_t) (CUR))

Calculate how many ticks are remaining.

NOTE: The data type returned should be signed.

Typedef Documentation

enc28j60_tick

typedef uint16_t enc28j60_tick

TODO: Change it to uint32_t or uint8_t, depending on the timer resolution.

This data type has to cover 1 millisecond.

NOTE: The code (ENC28J60_CALC_REMAINING_TICKS macro) assumes that the timer resets when it hits 0b1111...1111. If your timer does work differently, you may need to modify ENC28J60_CALC_REMAINING_TICKS.

Function Documentation

enc28j60_spi_advanced_transfer()

int enc28j60_spi_advanced_transfer	(	enc28j60 *	instance,
		const char *	tx1,
		char *	rx1,
		unsigned	length1,
		const char *	tx2,
		char *	rx2,
		unsigned	length2,
		enc28j60_spi_callback	on_finish
	)

This function performs (using DMA or blocking I/O) parallely transmision from 'tx1' buffer and reception into 'rx1' buffer (if 'rx1' is not null), and once this transmission is completed, performs transmission from 'tx2' (if not null) into 'rx2' (if not null).

If 'tx2' and 'rx2' is null (that is, when 'length2' is zero), the arguments 'tx2' and 'rx2' should be ignored and only repcetion from/into 'tx1'/'rx1' (if not null) should be done. If the callback is null, this function must block and return the error code, otherwise it may or may not block and the error code should be passed to the callback (and 0 returned).

NOTE: You must implement this function.

Parameters

instance	Pointer to enc28j60 struct (may contain hardware/software specific fields to determine which SPI to use).
tx1	Pointer pointing to data for transmission. Will not be null.
rx1	Pointer pointing to memory where data sohuld be received. May be null, in which case received data may be ignored. May also be same as 'tx'.
length1	Length of 'tx1' (and length of 'rx1' if 'rx1' is not null).
tx2	Pointer pointing to data for transmission. May be null.
rx2	Pointer pointing to memory where data sohuld be received. May be null, in which case received data may be ignored. May also be same as 'tx'.
length2	Length of 'tx2' (if 'tx2' is not null) and length of 'rx2' (if 'rx2' is not null).
on_finish	Callback which should be called when transfer is completed. If callback is null, the function must block and return error code, otherwise if callback is supplied the function may or may not block and callback must be called (with error code as parameter) and zero must be returned.

Returns

int error code, or 0 on success (return 0 when callback is supplied)

enc28j60_spi_transfer_join()

int enc28j60_spi_transfer_join

(

enc28j60 *

instance

)

This function should wait until SPI operation in progress (if any) finishes and then return.

NOTE: You must implement this function.

Returns

Error code or 0 on success.

enc28j60_spi_error_handler()

bool enc28j60_spi_error_handler	(	enc28j60 *	instance,
		int	error_code,
		uint16_t	retry
	)

This function is called before callback when non-zero error code is received from enc28j60_spi_transfer() or enc28j60_spi_advanced_transfer().

It tells whenever we should retry the transmission (by returning true), or simply fail and return the error code to the user (by returning false).

What exactly will this function do is dependant on the user. It may as well block infinitely and print error message on the screen, or always return true to retry the transmission if it's safe to do so.

NOTE: You must implement this function.

Parameters

instance	Pointer to enc28j60 struct
error_code	Non-zero error code received from enc28j60_spi_transfer() or enc28j60_spi_advanced_transfer()
retry	How many retries were there total (starting from 1).

Returns

bool true if tranmission should be retried, false if error should be returned/passed to a callback.

enc28j60_delay()

int enc28j60_delay	(	enc28j60 *	ins,
		enc28j60_tick	ticks
	)

Wait until given number of ticks passes.

Parameters

ins	Pointer to initialized enc28j60 struct.
ticks	How many ticks this function should wait before returning.

Returns

int Error code or 0 on success.

enc28j60_getticks()

int enc28j60_getticks	(	enc28j60 *	ins,
		enc28j60_tick *	ticks
	)

Get current number of ticks.

Parameters

ins	Pointer to initialized enc28j60 struct.
ticks	If not null, there should be stored the number of ticks.

Returns

int Error code or 0 on success.