weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files | Defines | Functions | Variables
Basic Ethernet communications drivers
+ + Low level system services + +

Overview

These driver functions are the link between

If appropriate these low level driver and helper functions can be used in the application software as well.

Files

file  enc28j60.h
 

weAutSys' (weAut_01's) 28J60 Ethernet driver


Defines

#define BFC_CMD
 Bit field clear command.
#define BFS_CMD
 Bit field set command.
#define COLSTAT
 collision is occurring (Bit number)
#define deSelectEnc()
 De-select the ENC28J60.
#define DPXSTAT
 configured for full-duplex (Bit number)
#define FRCLNK
 make link up even when no partner station detected (Bit number)
#define HDLDIS
 half duplex loopback disable (Bit number)
#define JABBER
 turn jabber correction off (Bit number)
#define JBSTAT
 transmission met jabber criteria since last PHSTAT1 read
#define LA_BFAST
 see PHLCON
#define LA_BSLOW
 see PHLCON
#define LA_COL
 see PHLCON
#define LA_DSC
#define LA_DSTAT
 see PHLCON
#define LA_LEDOFF
 see PHLCON
#define LA_LEDON
 see PHLCON
#define LA_LSRX
 see PHLCON
#define LA_LSTAT
 see PHLCON
#define LA_LSTXRX
 see PHLCON
#define LA_RX
 see PHLCON
#define LA_RXTX
 see PHLCON
#define LA_TX
 see PHLCON
#define LB_BFAST
 see PHLCON
#define LB_BSLOW
 see PHLCON
#define LB_COL
 see PHLCON
#define LB_DSC
 see PHLCON
#define LB_DSTAT
 see PHLCON
#define LB_LEDOFF
 see PHLCON
#define LB_LEDON
 see PHLCON
#define LB_LSRX
 see PHLCON
#define LB_LSTAT
 see PHLCON
#define LB_LSTXRX
 see PHLCON
#define LB_RX
 see PHLCON
#define LB_RXTX
 see PHLCON
#define LB_TX
 see PHLCON
#define LLSTAT
 link was up continuously since last PHSTAT1 read
#define LSTAT
 link is currently up (Bit number)
#define NOSTRCH
 do not stretch LED events (see PHLCON)
#define PFDPX
 full duplex capable (bit 12 is always set)
#define PHCON1
 PHY control register 1.
#define PHCON2
 PHY control register 2.
#define PHDPX
 half duplex capable (bit 11 is always set)
#define PHID1
 PHY identification register 1.
#define PHID2
 PHY identification register 2.
#define PHIE
 PHY interrupt enable register.
#define PHIR
 PHY interrupt request register.
#define PHLCON
 LED Configuration Register.
#define PHSTAT1
 PHY status register 1.
#define PHSTAT2
 PHY status register 2.
#define PLRITY
 polarity of TPIN is reversed
#define RBM_CMD
 Read buffer memory command.
#define RCR_CMD
 Read control register command.
#define RXSTAT
 PHY is currently receiving (Bit number)
#define selectEnc()
 Chip select the ENC28J60.
#define SYSRST_CMD   0xFF
 Reset ENC28J60 command.
#define TLSTRCH
 LED pulse stretch, long 140ms (see PHLCON)
#define TMSTRCH
 LED pulse stretch, medium 70ms (see PHLCON)
#define TNSTRCH
 LED pulse stretch, normal 40ms (see PHLCON)
#define tranceiveEnc(sendB)
 Transmit and receive one byte to / from ENC28J60.
#define tranceiveEnc2(sendB1, sendB2)
 Transmit two bytes and receive one byte to / from ENC28J60.
#define TXDIS
 disable twisted-pair transmitter hardware driver (Bit number)
#define TXSTAT
 PHY is currently transmitting (Bit number)
#define WBM_CMD
 Write buffer memory command.
#define WCR_CMD
 Write control register command.

Control registers

#define ESTAT
 ETHERNET status register.
#define CLKRDY
 Clock (oscillator) is ready (ESTAT bit number)
#define TXABRT
 The transmit request was aborted (ESTAT bit number)
#define ECON2
 ETHERNET control register 2.
#define AUTOINC
 automatic increment and wrap of RAM buffer addresses (ECON2 bit number)
#define PKTDEC
 decrement (received) packets count (ECON2 bit number)
#define PWRSV
 switch the PHY interface off (save power when not needed; ECON2 bit number)
#define VRPS
 only if PWRSV set voltage regulator to low current (ECON2 bit number)
#define ECON1
 ETHERNET control register 1.
#define TXRST
 Transmit only reset (ECON1 bit number)
#define RXRST
 Receive only reset (ECON1 bit number)
#define DMAST
 DMA operation (within internal RAM) start and busy bit (ECON1 bit number)
#define CSUMEN
 DMA hardware calculates checksums (ECON1 bit number)
#define TXRTS
 The transmit logic is attempting to transmit a packet (ECON1 bit number)
#define RXEN
 Receive enable.
#define EIE
 Ethernet interrupt enable register.
#define INTIE
 EIE bit number
#define PKTIE
 EIE bit number
#define DMAIE
 EIE bit number
#define LINKIE
 EIE bit number
#define TXIE
 EIE bit number
#define TXERIE
 EIE bit number
#define RXERIE
 EIE bit number
#define EIR
 Ethernet interrupt request register.
#define PKTIF
 EIR bit number
#define DMAIF
 EIR bit number
#define LINKIF
 EIR bit number
#define TXIF
 EIR bit number
#define TXERIF
 EIR bit number
#define RXERIF
 EIR bit number

Symbolic names for direct register access

The lower 5 bits (0..31) give the register number in each bank.

The bits 5 and 5 (mask 0x60) are used for the bank number (0..3 * 32).

uint8_t currentBank
 The currently set bank of registers.
#define ERDPTL
 The buffer read address register.
#define ERDPTH
 the buffer read address register
#define EWRPTL
 The buffer write address register.
#define EWRPTH
 the buffer write address register
#define ETXSTL
 The write / transmit buffer range.
#define ETXSTH
 the write buffer range
#define ETXNDL
 the write buffer range
#define ETXNDH
 the write buffer range
#define ERXSTL
 The read / receive buffer range.
#define ERXSTH
 the write buffer range
#define ERXNDL
 the write buffer range
#define ERXNDH
 the write buffer range
#define ERXRDPTL
 The receive buffer (already) read address register.
#define ERXRDPTH
 receive buffer already read
#define ERXWRPTL
 The receive buffer write address register.
#define ERXWRPTH
 receive buffer write
#define EDMASTL
 DMA start low byte.
#define EDMASTH
 DMA start high byte.
#define EDMANDL
 DMA end low byte.
#define EDMANDH
 DMA end high byte.
#define EDMADSTL
 DMA destination low byte.
#define EDMADSTH
 DMA destination high byte.
#define EDMACSL
 DMA checksum low byte.
#define EDMACSH
 DMA checksum high byte.
#define EHT0
 hash table byte 0
#define EHT1
 hash table byte 1
#define EHT2
 hash table byte 2
#define EHT3
 hash table byte 3
#define EHT4
 hash table byte 4
#define EHT5
 hash table byte 5
#define EHT6
 hash table byte 6
#define EHT7
 hash table byte 7
#define EPMM0
 pattern match mask byte 0
#define EPMM1
 pattern match mask byte 1
#define EPMM2
 pattern match mask byte 2
#define EPMM3
 pattern match mask byte 3
#define EPMM4
 pattern match mask byte 4
#define EPMM5
 pattern match mask byte 5
#define EPMM6
 pattern match mask byte 6
#define EPMM7
 pattern match mask byte 7
#define EPMCSL
 pattern match checksum low byte
#define EPMCSH
 pattern match checksum high byte
#define EPMOL
 pattern match offset low byte
#define EPMOH
 pattern match offset high byte
#define ERXFCON
 Ethernet receive filter control register.
#define EPKTCNT
 Ethernet package count.
#define MACON1
 MAC control register 1.
#define TXPAUS
 MAC control register 1 (bit number)
#define RXPAUS
 MAC control register 1 (bit number)
#define PASSALL
 MAC control register 1 (bit number)
#define MARXEN
 MAC control register 1 (bit number)
#define MACON2
 MAC control register 2 (inofficial)
#define MACON3
 MAC control register 3.
#define PADCFG2
 MAC control register 3 (bit number)
#define PADCFG1
 MAC control register 3 (bit number)
#define PADCFG0
 MAC control register 3 (bit number)
#define EXPSF64
 All short frames will be padded to 64 Bytes and have valid CRC appended.
#define EXPSF60
 All short frames will be padded to 60 Bytes and have valid CRC appended.
#define NOSFPAD
 No handling short frames.
#define DTCTVLAN
 Automatic handling short frames.
#define TXCRCEN
 MAC control register 3 (bit number)
#define PHIDREN
 MAC control register 3 (bit number)
#define HFRMEN
 MAC control register 3 (bit number)
#define FRMLNEN
 MAC control register 3 (bit number)
#define FULDPX
 MAC control register 3 (bit number)
#define MACON4
 MAC control register 4.
#define DEFER
 MAC control register 4 (bit number)
#define BPEN
 MAC control register 4 (bit number)
#define NOBKOFF
 MAC control register 4 (bit number)
#define MABBIPG
 back-to-back inter-packet gap
#define MAIPGL
 non back-to-back inter-packet gap low
#define MAIPGH
 non back-to-back inter-packet gap high
#define MACLCON1
 retransmission maximum (4 bit)
#define MACLCON2
 collision window (6 bit)
#define MAMXFLL
 maximum frame length low byte
#define MAMXFLH
 maximum frame length high byte
#define MICMD
 MII command register.
#define MIISCAN
 MII command register (bit number)
#define MIIRD
 MII command register (bit number)
#define MIREGADR
 MII register address register.
#define MIWRL
 MII write data low byte.
#define MIWRH
 MII write data high byte.
#define MIRDL
 MII read data low byte.
#define MIRDH
 MII read data high byte.
#define MAADR1
 MAC address register (first)
#define MAADR2
 MAC address register.
#define MAADR3
 MAC address register.
#define MAADR4
 MAC address register.
#define MAADR5
 MAC address register.
#define MAADR6
 MAC address register (last)
#define EBSTSD
 built-in self test fill seed
#define EBSTCON
 Ethernet self test control register.
#define EBSTCSL
 built-in self test checksum low byte
#define EBSTCSH
 built-in self test checksum high byte
#define MISTAT
 MII status register.
#define NVALID
 MII status register (bit number)
#define SCAN
 MII status register (bit number)
#define BUSY
 MII status register (bit number)
#define EREVID
 Ethernet revision ID (5 bit, R/O)
#define ECOCON
 Clock output control.
#define EFLOCON
 EFLOCON (Ethernet Flow Control.
#define EPAUSL
 Pause timer value low byte.
#define EPAUSH
 Pause timer value high byte.
#define REG_MASK   0x1F
 Mask for register number bits in symbolic register address.
#define REG_BANK_MASK   0x60
 Mask for bank bits in symbolic register address.
#define SPI_BANK_MASK
 Mask for bank bits in control register.
#define KEY_REGISTERS   0x1B
 First number of common registers.

Per packet control bits for transmission settings

#define PHUGEEN
 Huge frame enable (bit number)
#define PPADEN
 per packet padding enable (bit number)
#define PCRCEN
 per packet CRC enable (bit number)
#define POVERRIDE
 packet overrides (bit number)

Functions

void clearBitfield (uint8_t regAdd, uint8_t data)
 Clear bits in a control register.
void encDisablePowersave (void)
 Leave the power safe mode.
void encEnablePowersave (void)
 Go to power safe mode.
void encGetMacAdd (eth_addr_t *mac)
 Read the current MAC address.
uint8_t encSetMacAdd (eth_addr_t *mac)
 Set the MAC address.
void putBufferMemory (uint8_t data)
 Write one byte to ENC28J60's memory buffer.
void readBufferMemory (uint8_t *dest, uint16_t n)
 Read n bytes from ENC28J60's memory buffer.
uint8_t readControlRegister (uint8_t regAdd)
 Read a control register.
uint16_t readPhysicalRegister (uint8_t regAdd)
 Read one of ENC28J60's physical registers.
uint8_t setBank (uint8_t regAdd)
 Sets a register bank (in ECON1) if necessary for the given register.
void setBitfield (uint8_t regAdd, uint8_t data)
 Set bits in a control register.
void writeBufferMemory (uint8_t *source, uint16_t n)
 Write n bytes to ENC28J60's memory buffer.
void writeControlRegister (uint8_t regAdd, uint8_t data)
 Write a control register.
void writePhysicalRegister (uint8_t regAdd, uint16_t data)
 Write to one of ENC28J60's physical registers.

Variables

uint8_t receiveStatVec []
 Receive status vector.
uint8_t transmitStatVec []
 Transmission status vector.

Define Documentation

#define PHLCON

LED Configuration Register.

Eleven bits (1..11) of this register control the operation of the two LEDs that may be driven by the ENC28J60. They are usually, as in the weAut_01 board, integrated in the RJ45 jack.

Bits 15 and 14 must be written as 1; bits 13, 12 and 0 must be written as 0.

Both LEDs, referred to as LEDA and LEDB, have the same set of options coded to other bit positions. Available bit field options by macros are named accordingly beginning with LA or LB:

Lx_DSC:   Duplex status and collision activity (always stretched)
Lx_LSTXRX: Link status transmission and receive activity (always stretched)
Lx_LSRX: Link status receive activity (always stretched)
Lx_BSLOW: Blink slow
Lx_BFAST: Blink fast
Lx_LEDOFF: LED off
Lx_LEDON: LED on
Lx_RXTX: Receive and Transmission activity
Lx_DSTAT: Duplex status
Lx_LSTAT: Link status
Lx_COL:   Collision activity (stretchable)
Lx_RX:   Receive activity (stretchable)
Lx_TX:   Transmit activity (stretchable)

The configuration for LED on's stretching for stretchable events is common for both LEDs.

#define LA_DSC

see PHLCON

#define RXEN

Receive enable.

Packets complying to the filter criteria set will be written into the receive buffer (ECON1 bit number).

#define ERDPTL

The buffer read address register.

The ENC28J60's 8K dual port RAM can be read using the (indirect) (13 bit) address in ERDPTH ERDPTL .

If the AUTOINC bit is set in ECON2 this register is incremented after each read automatically wrapping around within the receive buffer range ERXST .. ERXND.

#define ERDPTH

the buffer read address register

See also:
ERDPTL
#define EWRPTL

The buffer write address register.

The ENC28J60's 8K dual port RAM can be written using the (indirect) (13 bit) address in EWRPTH : EWRPTL .

If the AUTOINC bit is set in ECON2 this address is incremented after each write automatically wrapping around within the RAM address range 0x0000 .. 0x1FFF .

#define EWRPTH

the buffer write address register

See also:
EWRPTL
#define ETXSTL

The write / transmit buffer range.

The write buffer is located in the address range ETXSTH : ETXSTL .. ETXNDH : ETXNDL within the ENC28J60's 8K dual port RAM.

If the AUTOINC bit is set in ECON2 this is incremented after each read automatically wrapping around within range 0x0000 .. 0x1FFF i.e. the write wrapping is independent of this setting.

See also:
ERXSTL
#define ETXSTH

the write buffer range

See also:
ETXSTL
#define ETXNDL

the write buffer range

See also:
ETXSTL
#define ETXNDH

the write buffer range

See also:
ETXSTL
#define ERXSTL

The read / receive buffer range.

The read buffer is located in the address range ERXSTH : ERXSTL .. ERXNDH : ERXNDL within the ENC28J60's 8K dual port RAM.

If the AUTOINC bit is set in ECON2 this is incremented after each read automatically wrapping around within the receive buffer address range ERXST .. ERXND.

See also:
ETXSTL
#define ERXSTH

the write buffer range

See also:
ERXSTL
#define ERXNDL

the write buffer range

See also:
ERXSTL
#define ERXNDH

the write buffer range

See also:
ERXSTL
#define ERXRDPTL

The receive buffer (already) read address register.

The address ERXRDPTH : ERXRDPTL is the index in the ENC28J60's 8K dual port RAM to where received bytes were processed by the software.

This location is never overwritten by the receiver.

See also:
ERXWRPTL
#define ERXRDPTH

receive buffer already read

See also:
ERXRDPTL
#define ERXWRPTL

The receive buffer write address register.

The ENC28J60's 8K dual port RAM is written while receiving using the (indirect 13 bit) address in ERXWRPTH : ERXWRPTL auto-incrementing it after each received byte.
The address ERXRDPTH : ERXRDPTL will never be overwritten

#define ERXWRPTH

receive buffer write

See also:
ERXWRPTL
#define EXPSF64

All short frames will be padded to 64 Bytes and have valid CRC appended.

MAC control register 3 (bit pattern)

#define EXPSF60

All short frames will be padded to 60 Bytes and have valid CRC appended.

MAC control register 3 (bit pattern)

#define NOSFPAD

No handling short frames.

MAC control register 3 (bit pattern)

#define DTCTVLAN

Automatic handling short frames.

The MAC will automatically detect VLAN Protocol frames (by 8100h type field). It pads short frames to 64 bytes if it's a valid VLAN frame or to 60 bytes otherwise. A valid CRC will then be appended.

MAC control register 3 (bit pattern)

#define MIREGADR

MII register address register.

This control register (5 bit) is used to address other register types. 16 bit registers are indirectly accessed via (this) address register and write respectively read registers.

See also:
MIWRL
MIWRH
MIRDL
MIRDH
#define MIWRL

MII write data low byte.

See also:
MIREGADR
#define MIWRH

MII write data high byte.

See also:
MIREGADR
#define MIRDL

MII read data low byte.

See also:
MIREGADR
#define MIRDH

MII read data high byte.

See also:
MIREGADR
#define SPI_BANK_MASK

Mask for bank bits in control register.

The last 2 Bits of ECON1 are the bank value (0..3).

#define KEY_REGISTERS   0x1B

First number of common registers.

Control registers live in 4 banks of each theoretically 32 registers.

The last "key" or "common" registers appear in all for banks. For them there's no need to even consider bank switching.

#define deSelectEnc ( )

De-select the ENC28J60.

Does the de-select after (waiting for) send (on UART as SPI 2 to ) is completed.

#define tranceiveEnc2 (   sendB1,
  sendB2 
)

Transmit two bytes and receive one byte to / from ENC28J60.

Parameters:
sendB1the byte to be sent first
sendB2the second byte to be sent
Returns:
the (second) byte read from SPI while transmitting sendB2

Function Documentation

uint8_t readControlRegister ( uint8_t  regAdd)

Read a control register.

This function reads one of the ENC28J60's control registers.
The register's symbolic address consists of the register number (0..31 within the register bank) + the bank number (0..3)*32. All symbolic control register names — i.e. macros — within ENC28J60.h are formed in this way.
The bank is switched only if necessary.

All control registers are 8 bit. They fall into one of three categories: ETH, MAC and MII. One step bit set and bit clear operations eliminate the need of going through read/modify/write — but only for the ETH type.

For reading the MAC or MII registers the answer will be prepended by an extra or dummy byte. In other words: The ENC28J60 needs 16 SPI clocks to read from an ETH register and 24 SPI clocks to read from a MAC/MII register. This (little) complication is, of course, handled by this function.

Parameters:
regAddthe register's symbolic address
Returns:
it's value
See also:
writeControlRegister
setBank
setBitfield
void writeControlRegister ( uint8_t  regAdd,
uint8_t  data 
)

Write a control register.

This function writes one of the ENC28J60's control registers.
The bank is switched if necessary.

Parameters:
regAddthe register's symbolic address
datathe new value
See also:
readControlRegister
void setBitfield ( uint8_t  regAdd,
uint8_t  data 
)

Set bits in a control register.

This is an OR operation on the content of the register regAdd. For ETH type control registers it is done internally by the ENC28J60 saving a read modify write cycle.

For MII and MAC registers this internal OR is not available and hence the read and if necessary modify + write is done.

Parameters:
regAddsymbolic register address
datathe bits to be set
See also:
readControlRegister
clearBitfield
void clearBitfield ( uint8_t  regAdd,
uint8_t  data 
)

Clear bits in a control register.

This is an AND NOT on the content of the register regAdd. Conditions for a quick internal implementation by the ENC28J60 are the same as for setBitfield.

Parameters:
regAddsymbolic address of the register to be modified
datathe bits to be reset
See also:
readControlRegister
setBitfield
uint16_t readPhysicalRegister ( uint8_t  regAdd)

Read one of ENC28J60's physical registers.

This function handles the indirect access to those registers. All physical registers are 16 bit and can be read or written as whole words only.

The complication of being only indirectly accessible via MIREGADR etc. is handled by this function.

Parameters:
regAddthe register address
Returns:
its value
See also:
writePhysicalRegister
void writePhysicalRegister ( uint8_t  regAdd,
uint16_t  data 
)

Write to one of ENC28J60's physical registers.

Parameters:
regAddthe register address
datathe (16 bit) value to be written
See also:
readPhysicalRegister
void readBufferMemory ( uint8_t *  dest,
uint16_t  n 
)

Read n bytes from ENC28J60's memory buffer.

This function reads a sequence of bytes from the dual port RAM indirectly addressed by the ERXRDPT control registers. For n > 1 this usually makes sense only if auto-increment is on.

Parameters:
destpointer to buffer in RAM to write to
nnumber of bytes to read from ENC28J60's memory
void putBufferMemory ( uint8_t  data)

Write one byte to ENC28J60's memory buffer.

This function writes to the dual port RAM byte indirectly addressed by the EWRPT control registers.

Parameters:
datato be written into the buffer memory
void writeBufferMemory ( uint8_t *  source,
uint16_t  n 
)

Write n bytes to ENC28J60's memory buffer.

This function writes a sequence of bytes to the dual port RAM byte indirectly addressed by the EWRPT control registers. This usually makes sense only if auto-increment is on.

Parameters:
sourcepointer to data in RAM to be written to ENC28J60's memory
nnumber of bytes to be transferred from RAM to ENC
uint8_t setBank ( uint8_t  regAdd)

Sets a register bank (in ECON1) if necessary for the given register.

This function does nothing if no bank switch is needed to access the register regAdd

Parameters:
regAddsymbolic address of the register (bank bits relevant)
Returns:
the lower 5 bits (the "bankless" address) of regAdd
void encGetMacAdd ( eth_addr_t mac)

Read the current MAC address.

The MAC address will be read from the Ethernet driver ( ENC28J60) and put in the structure supplied.

Parameters:
macthe (6 byte) address structure
uint8_t encSetMacAdd ( eth_addr_t mac)

Set the MAC address.

The MAC address from the structure supplied will be written to the Ethernet driver ( ENC28J60).

This initialisation function is usually called as

using the Ethernet stack's (uIP's) set MAC address for the driver.
Both the driver's and the stack's setting must be kept the same.

The uIP's default / initialisation value for actMACadd is

 {0x40,0x1B,0x50,0xCA,0xFE,0x01} 


40 is "locally assigned unicast 0"
1B50 read "IBS 0" or Inbetriebsetzung (comissioning to use) 0 is a fixed preset for first test or standalone use
CAFE01 in this context means "check all functional element of weAut01

As this is one of the most basic ENC28J60 initialisations this function checks the chips and the SPI's operation by re-reading the ENC's MAC address registers. 0 is returned only if this check passes.

Note:
This test was implemented because the CLKRDY bit test, that would do the same basic hardware testing, simply does not work on most ENC cip releases and hence can as well be omitted.
Parameters:
macthe (6 byte) address structure
Returns:
0 : OK; 1..6 the number of failed check reads
void encEnablePowersave ( void  )

Go to power safe mode.

The ENC28J60 can be set to save power (if not used).

void encDisablePowersave ( void  )

Leave the power safe mode.

See also:
encEnablePowersave

Variable Documentation

uint8_t currentBank

The currently set bank of registers.

Holds only the bank select bits, BSEL1:BSEL0 (mask 0x03) as in ECON1 register shifted 5 bits to left resp. * 32 (mask 0x60) as in the symbolic names.

Not to be modified by user software.

uint8_t receiveStatVec[]

Receive status vector.

Holds ENC's 4 byte receive status vector belonging to the last received package.

uint8_t transmitStatVec[]

Transmission status vector.

Used to see any failures during transmission. It is generated after the ESTAT.TXABRT flag is set by the ENC28J60.