Firmware APIs

C functions

Common functions

Functions

void enableHkSpi(bool is_enable)

Enable or disable the housekeeping SPI This function writes to the housekeeping disenable register inside the housekeeping

Note

When this register asserted housekeeping SPI can’t be used and GPIOs[3] which is CSB can be used as any other Caravel GPIOs

Warning

By default the housekeeping SPI is enabled to use GPIOs[3] freely it should be disabled.

Parameters:

is_enable – when 1 (true) housekeeping is active, 0 (false) housekeeping is disabled

void dummyDelay(int num)

Insert delay

Parameters:

num – number of delays steps. step is increment local variable and check it’s value

GPIO

Enums

enum gpio_mode

GPIOs possible modes

name

description

GPIO_MODE_MGMT_STD_INPUT_NOPULL

Management input with no pull (floating is read as Z)

GPIO_MODE_MGMT_STD_INPUT_PULLDOWN

Management input pull-down (floating is read as 0)

GPIO_MODE_MGMT_STD_INPUT_PULLUP

Management input pull-up (floating is read as 1)

GPIO_MODE_MGMT_STD_OUTPUT

Management output

GPIO_MODE_MGMT_STD_BIDIRECTIONAL

Management bi-direction

GPIO_MODE_MGMT_STD_ANALOG

Management Analog

GPIO_MODE_USER_STD_INPUT_NOPULL

User input with no pull (floating is read as Z)

GPIO_MODE_USER_STD_INPUT_PULLDOWN

User input pull-down (floating is read as 0)

GPIO_MODE_USER_STD_INPUT_PULLUP

User input pull-up (floating is read as 1)

GPIO_MODE_USER_STD_OUTPUT

User output

GPIO_MODE_USER_STD_BIDIRECTIONAL

User bi-direction

GPIO_MODE_USER_STD_OUT_MONITORED

User Monitor same as output

GPIO_MODE_USER_STD_ANALOG

User Analog

Values:

Functions

void GPIOs_configureAll(enum gpio_mode config)

Configure all GPIOs with the config

Note

These configurations will not be change the GPIOs modes until calling GPIOs_loadConfigs()

Parameters:

config – is configuration of type gpio_mode

void GPIOs_loadConfigs()

Load the configurations changes to the GPIOs

void GPIOs_configure(int gpio_num, enum gpio_mode config)

Configure one GPIO with the input config

Note

These configurations will not be change the GPIOs modes until calling GPIOs_loadConfigs()

Parameters:

  • config – is configuration of type gpio_mode

  • gpio_num – is GPIO number it can have values from 0 to 37

void GPIOs_writeLow(unsigned int data)

Write to the low 32 GPIOs GPIOS[31:0]

Examples:

  • GPIOs_writeLow(0x1); // write 1 to GPIO [0] and write 0 in the remaining 31 GPIOs 

  • GPIOs_writeLow(0x5); // write 1 to GPIO [0] and GPIO [3] and write 0 in the remaining 30 GPIOs

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

data – is the data sent to the GPIOs

void GPIOs_writeHigh(unsigned int data)

Write to the highest 6 GPIOs GPIOS[37:32]

Examples:

  • GPIOs_writeHigh(0x1); // write 1 to GPIO [32] and write 0 in the remaining 5 GPIOs

  • GPIOs_writeHigh(0x5); // write 1 to GPIO [32] and 34 and write 0 in the remaining 4 GPIOs

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

data – is the data sent to the GPIOs

void GPIOs_writeLowHigh(long data)

Write to the 38 GPIOs GPIOS[37:0]

Examples:

  • GPIOs_writeLowHigh(0x1); // write 1 to GPIO [0] and write 0 in the remaining 37 GPIOs 

  • GPIOs_writeLowHigh(0x5); // write 1 to GPIO [0] and GPIO [3] and write 0 in the remaining 36 GPIOs

  • GPIOs_writeLowHigh(0x100000000); // write 1 to GPIO [32] and write 0 in the remaining 36 GPIOs
Todo:

verify this function

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

data – is the data sent to the GPIOs

unsigned int GPIOs_readHigh()

Read the highest 6 GPIOs GPIOS[37:32]

Note

For Reading value from the GPIOs, the GPIO should be configured as management input. otherwise 0 would be read

unsigned int GPIOs_readLow()

Read low 32 GPIOs GPIOS[31:0]

Note

For Reading value from the GPIOs, the GPIO should be configured as management input. otherwise 0 would be read

void GPIOs_waitLow(unsigned int data)

wait over the lowest 32 GPIOsto equal the data passed

Examples:

  • GPIOs_waitLow(0x1); // function would return only when GPIO [0]==1 and rest of 31 GPIOs= 0  

  • GPIOs_waitLow(0x5); // function would return only when GPIO [0]==1 and GPIO [3]==1 and rest of 30 GPIOs = 0

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

data – is the data that should wait until sent to the GPIOs

void GPIOs_waitHigh(unsigned int data)

wait over the highest 6 GPIOs to equal the data passed

Examples:

  • GPIOs_waitHigh(0x1); // function would return only when GPIO [32]==1 and rest of 5 GPIOs = 0  

  • GPIOs_waitHigh(0x5); // function would return only when GPIO [32]==1 and GPIO [34]==1 and rest of 4 GPIOs = 0

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

data – is the data that should wait until sent to the GPIOs

void GPIOs_waitLowWithMask(unsigned int data, unsigned int mask)

wait over the masked lowest 32 GPIOs to equal the data passed

Examples:

  • GPIOs_waitLowWithMask(0x1,0xF); // function would return only when GPIO [0]==1 and GPIO [3:1]==0 and don't care about the rest of GPIOs  

  • GPIOs_waitLowWithMask(0x5,0x7); // function would return only when GPIO [0]==1 and GPIO [3]==1 and GPIO [2]==0 and don't care about the rest of GPIOs

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

  • data – is the data that should wait until sent to the GPIOs

  • mask – mask over the each GPIO if the mask value is 0 the this GPIO value are ignored

void GPIOs_waitHighWithMask(unsigned int data, unsigned int mask)

wait over the masked highest 6 GPIOs to equal the data passed

Examples:

  • GPIOs_waitHighWithMask(0x1,0xF); // function would return only when GPIO [32]==1 and GPIO [35:33]==0 and don't care about the rest of GPIOs  

  • GPIOs_waitHighWithMask(0x5,0x7); // function would return only when GPIO [32]==1 and GPIO [34]==1 and GPIO [33]==0 and don't care about the rest of GPIOs

Note

For writing by this function to be seen at the GPIO the GPIO has to be configured as management output

Parameters:

  • data – is the data that should wait until sent to the GPIOs

  • mask – mask over the each GPIO if the mask value is 0 the this GPIO value are ignored

Interrupts

Functions

void IRQ_enableExternal1(bool is_enable)

Enable or disable external1 interrupt GPIO[7]

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableExternal2(bool is_enable)

Enable or disable external2 interrupt GPIO[12]

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableUser0(bool is_enable)

Enable or disable user0 interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableUser1(bool is_enable)

Enable or disable user1 interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableUser2(bool is_enable)

Enable or disable user1 interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableTimer(bool is_enable)

Enable or disable timer0 interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableUartTx(bool is_enable)

Enable or disable UART tx interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_enableUartRx(bool is_enable)

Enable or disable UART rx interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

void IRQ_hkSpi(bool is_enable)

Enable or disable SPI interrupt

Parameters:

is_enable – when 1 (true) interrupt is active and firmware would detect if happened, 0 (false) interrupt is disabled and firmware would not detect if happened

Logic analyzers

Enums

enum la_reg_number

Logic analyzers registers

name

value

description

LA_REG_0

0

First LA register probs [31:0]

LA_REG_1

1

Second LA register probs [63:32]

LA_REG_2

2

Third LA register probs [95:64]

LA_REG_3

3

Fourth LA register probs [127:96]

Values:

Functions

void LogicAnalyzer_inputEnable(enum la_reg_number reg_num, unsigned int is_enable)

Setting logic analyzer input enable. High to enable.

Enable as input from the user project to the firmware.

Parameters:

  • reg_num – logic analyzer register to write to. Usually not all caravel versions has the same numbers of LA registers They might have 4 registers (128 probs between firmware and user project) or registers (64 probs between firmware and user project)

  • is_enable – 32 bits each bit indicate if the corresponding probe enabled as input

void LogicAnalyzer_outputEnable(enum la_reg_number reg_num, unsigned int is_enable)

Setting logic analyzer output enable. Low to enable.

Enable as output from the firmware to the user project.

Parameters:

  • reg_num – logic analyzer register to write to. Usually not all caravel versions has the same numbers of LA registers They might have 4 registers (128 probs between firmware and user project) or registers (64 probs between firmware and user project)

  • is_enable – 32 bits each bit indicate if the corresponding probe enabled as output

void LogicAnalyzer_write(enum la_reg_number reg_num, unsigned int data)

Write data through logic analyzers from firmware to user project

Note

For this to work correctly probe should be configured as output

Parameters:

  • reg_num – logic analyzer register to write to. Usually not all caravel versions has the same numbers of LA registers They might have 4 registers (128 probs between firmware and user project) or registers (64 probs between firmware and user project)

  • data – data to write through logic analyzers

unsigned int LogicAnalyzer_read(enum la_reg_number reg_num)

Read data through logic analyzers from user project to firmware

Note

For this to work correctly probe should be configured as output

Parameters:

reg_num – logic analyzer register to read from. Usually not all caravel versions has the same numbers of LA registers They might have 4 registers (128 probs between firmware and user project) or registers (64 probs between firmware and user project)

Management GPIO

Functions

void ManagmentGpio_inputEnable()

Configure management GPIO as input

void ManagmentGpio_outputEnable()

Configure management GPIO as output

void ManagmentGpio_ioEnable()

Configure management GPIO as bi-direction

void ManagmentGpio_disable()

Configure management GPIO as floating It’s not connected as input or output

void ManagmentGpio_write(bool data)

Write data in management GPIO

Note

This function works when management GPIO configured as output

Parameters:

data – data to write at management GPIO possible values are 0 and 1

int ManagmentGpio_read()

Read data in management GPIO

Note

This function works correctly when management GPIO configured as input If management doesn’t connect to anything the firmware would read “0”

void ManagmentGpio_wait(bool data)

Wait over management GPIO to equal data

Note

This function works correctly when management GPIO configured as input

Parameters:

data – data to wait over

SPI master

Functions

void MSPI_write(char c)

Write byte (8bits) through SPI master

Parameters:

c – byte to write range 0x0 to 0xFF

char MSPI_read()

Read byte (8bits) through SPI master

void MSPI_enable(bool is_enable)

Enable or disable the master SPI

Parameters:

is_enable – when 1 (true) master SPI is active, 0 (false) master SPI is disabled

void MSPI_enableCS(bool is_enable)

assert or deassert chip select

Parameters:

is_enable – when 1 (true) chip select is asserted, 0 (false) chip select is deasserted

Timer0

Functions

void timer0_configureOneShot(unsigned int count)

Start Timer in oneshot countdown mode start value is count

Parameters:

count – start value in the counter > 0

void timer0_configurePeriodic(unsigned int count)

Start counter in periodic countdown mode start value is count

Timer will roll over to the count value when it reaches 0

Parameters:

count – start value in the counter > 0

void timer0_enable(bool is_enable)

Enable or Disable timer0

Parameters:

is_enable – when 1 (true) timer0 is enable (start counting), 0 (false) timer0 is disabled

unsigned int timer0_readValue()

Get timer current value

UART

Functions

void UART_enableTX(bool is_enable)

Enable or disable TX of UART

Note

Some caravel CPU enable and disable UART TX and RX together

Parameters:

is_enable – when 1(true) UART TX enable, 0 (false) UART TX disable

void UART_enableRX(bool is_enable)

Enable or disable RX of UART

Note

Some caravel CPU enable and disable UART TX and RX together

Parameters:

is_enable – when 1(true) UART RX enable, 0 (false) UART RX disable

char UART_readChar()

Wait receiving ASCII symbol and return it.

Return the first ASCII symbol of the UART received queue

RX mode have to be enabled

void UART_popChar()

Pop the first ASCII symbol of the UART received queue

UART_readChar() function would keeping reading the same symbol unless this function is called

char *UART_readLine()

read full line msg and return it

void print(const char *p)

Send ASCII symbol or symbols through UART

TX mode have to be enabled

void UART_sendChar(char c)

Send ASCII char through UART

TX mode have to be enabled

Parameters:

c – ASCII char to send

void UART_sendInt(int data)

Send int through UART the int would be sent as 8 hex characters

TX mode have to be enabled

Parameters:

c – int to send

User Space

Functions

void User_enableIF()

Enable communication between firmware and user project through wishbone

Warning

This necessary when reading or writing are needed between wishbone and user project if interface isn’t enabled no ack would be receive and the writing or reading command will be stuck

void USER_writeWord(unsigned int data, int offset)

Write word (4 bytes) at user address space 32 bit register

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

  • data – world data to write

  • offset – the offset of the register to write. Origin at the user project address

unsigned int USER_readWord(int offset)

Read word (4 bytes) at user address space 32 bit register

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

offset – the offset of the register to write. Origin at the user project address

void USER_writeHalfWord(unsigned short data, unsigned int offset, bool is_first_word)

Write half word (2 bytes) at user address space 32 bit register

is first word

-

1

1

0

0

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

  • data – half world data to write

  • offset – the offset of the register to write. Origin at the user project address

  • is_first_word – the offset of the register to write. Origin at the user project address

unsigned short USER_readHalfWord(unsigned int offset, bool is_first_word)

Read half word (2 bytes) at user address space 32 bit register

is first word

-

1

1

0

0

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

  • offset – the offset of the register to write. Origin at the user project address

  • is_first_word – the offset of the register to write. Origin at the user project address

void USER_writeByte(unsigned char data, unsigned int offset, unsigned char byte_num)

Write byte at user address space 32 bit register

byte_num

-

0

1

2

3

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

  • data – byte data to write

  • offset – the offset of the register to write. Origin at the user project address

  • byte_num – number of the in the 4 bytes register (32 bits)

unsigned char USER_readByte(unsigned int offset, unsigned char byte_num)

Read byte at user address space 32 bit register

byte_num

-

0

1

2

3

address

offset

byte0

byte1

byte2

byte3

0x0

0

0

1

2

3

0x4

1

4

5

6

7

0x8

2

8

9

10

11

0xC

3

12

13

14

15

Note

Since offset is a word (4 bytes) and address space represent bytes, offset = address /4

For example if project caravel space are 26 address bit offset = wb_addr_i[25:0]/4

Parameters:

  • offset – the offset of the register to write. Origin at the user project address

  • byte_num – number of the in the 4 bytes register (32 bits)