libparanut
A Hardware Abstraction Layer for ParaNut Architectures.

Functions for getting the status of your ParaNut and halting cores. More...

Collaboration diagram for Base Module:
PN_NUMC pn_numcores (void)
 Get the number of cores in your system. More...
 
PN_CMSK pn_m2cap (void)
 Check which cores are capable of Mode 2 operation. More...
 
PN_CMSK pn_m2cap_g (PN_NUMG groupnum)
 Check which cores are capable of Mode 2 operation. More...
 
PN_CMSK pn_m3cap (void)
 Check which cores are capable of Mode 3 operation. More...
 
PN_CMSK pn_m3cap_g (PN_NUMG groupnum)
 Check which cores are capable of Mode 3 operation. More...
 
PN_CID pn_coreid (void)
 Get the ID of the core that this function is executed on. More...
 
PN_CID pn_coreid_g (PN_NUMG *groupnum)
 Get the ID and group number of the core that this code is running on. More...
 
void pn_halt (void)
 Halt whatever core the function is executed on. More...
 
int pn_halt_CoPU (PN_CID coreid)
 Halts a CoPU. More...
 
int pn_halt_CoPU_m (PN_CMSK coremask)
 Halts one or more CoPUs. More...
 
int pn_halt_CoPU_gm (PN_CMSK *coremask_array, PN_NUMG array_size)
 Halts the CoPUs specified in the coremask_array. More...
 
unsigned int pn_clock_freq (void)
 Returns system clock frequency in Hz. More...
 
unsigned int pn_timebase_us (void)
 Returns machine timer timebase in us. More...
 
long long int pn_time_ns (void)
 Returns system time in ns. Does not care for overflow. More...
 
int pn_simulation (void)
 Checks if we run in simulation instead of real hardware. More...
 

Detailed Description

Functions for getting the status of your ParaNut and halting cores.

Concerning the _g functions: If your ParaNut implementation has more cores than what is the standard register size on your system (i.e. register size is 32, but you got more than 32 cores including the CePU), you have to chose the group of cores that you want to talk to. For that, most functions in this section have a group version (suffix _g) which has an additional group parameter.

This works the following way: If your register size is 32, than the CePU is in group 0 (0x00000000) and is always represented by the first bit in the coremasks (0x00000001). The first CoPU is also in group 0 and represented by the second bit (0x00000002). After that comes the second CoPU, represented by 0x00000004. And so on until CoPU 30. The 31st CoPU is then represented by group 1 (0x00000001) and the first bit (0x00000001). The 63rd CoPU is represented by group 2 (0x00000002) and the first bit (0x00000001). The 95th CoPU is represented by group 3 (0x00000003) and the first bit (0x00000001). This information may become untrue if a big-endian version of the ParaNut is ever released.

For further information on this topic, you should check the ParaNut Manual itself. Also, the documentation on the ParaNut Modes that is included in here could clear some things up.

Function Documentation

◆ pn_clock_freq()

unsigned int pn_clock_freq ( void  )

Returns system clock frequency in Hz.

Returns the value of the paranut pnclockinfo register which should contain the current system clock frequency in Hz. If this value is not what you would expect check your implementation.

Returns
System clock frequency in Hz.

◆ pn_coreid()

PN_CID pn_coreid ( void  )

Get the ID of the core that this function is executed on.

Returns
The core ID. Starts with 0 for CePU. Can not return an error.

◆ pn_coreid_g()

PN_CID pn_coreid_g ( PN_NUMG groupnum)

Get the ID and group number of the core that this code is running on.

Todo:
Currently only a stub. Will therefore always return PN_ERR_NOIMP.
Parameters
[out]groupnumis a reference to be filled with the group number of the core.
Returns
The core ID. Starts with 0 for CePU. Does not start again when in another group than group 0. Can not return an error.
Todo:
Currently only a stub. Will therefore always return PN_ERR_NOIMP.
Parameters
[out]groupnumis a reference to be filled with the group number of the core.
Returns
The core ID. Starts with 0 for CePU. Does not start again when in another group than group 0. Can not return an error.
Todo:
Group function implementation.

◆ pn_halt()

void pn_halt ( void  )

Halt whatever core the function is executed on.

If executed on a core, it will be set to Mode 0 and stop operation. Causes reset of program counter to reset address on a Mode 2 capable CPU.

If executed on CePU, also halts all other CoPUs on system.

See documentation of Modes for more information.

This function returns nothing because it should not be possible for any core to leave this state on its own.

◆ pn_halt_CoPU()

int pn_halt_CoPU ( PN_CID  coreid)

Halts a CoPU.

Sets the CoPU with the given ID into a halted state (Mode 0).

See documentation of Modes for more information.

Cannot be executed on CoPU.

Halting an already halted core results in failure (PN_ERR_PARAM) to aid debugging.

Todo:
Not yet implemented for given core IDs outside of group 0. Will return PN_ERR_NOIMP in this case.
Parameters
[in]coreidis the ID of the CoPUs you want to halt. Since ID 0 represents the CePU, this function will throw an error when given 0 to aid debugging. If you want the CePU to halt, use function pn_halt().
Returns
Either PN_SUCCESS, PN_ERR_PARAM or PN_ERR_COPU.

Sets the CoPU with the given ID into a halted state (Mode 0).

See documentation of Modes for more information.

Cannot be executed on CoPU.

Halting an already halted core results in failure (PN_ERR_PARAM) to aid debugging.

Todo:
Not yet implemented for given core IDs outside of group 0. Will return PN_ERR_NOIMP in this case.
Parameters
[in]coreidis the ID of the CoPUs you want to halt. Since ID 0 represents the CePU, this function will throw an error when given 0 to aid debugging. If you want the CePU to halt, use function pn_halt().
Returns
Either PN_SUCCESS, PN_ERR_PARAM or PN_ERR_COPU.

◆ pn_halt_CoPU_gm()

int pn_halt_CoPU_gm ( PN_CMSK coremask_array,
PN_NUMG  array_size 
)

Halts the CoPUs specified in the coremask_array.

Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

Sets the CoPUs represented by bitmask and their position in the array (= their group number) into a halted state (Mode 0).

See documentation of Modes for more information.

Cannot be executed on CoPU.

Halting an already halted core results in failure (PN_ERR_PARAM) to aid debugging.

Parameters
[in]coremask_arrayis a pointer to the start of a coremask array. The position of the mask in the array represents the group number of the cores. When all bits are set to 0, this function will return an error (PN_ERR_PARAM) to aid debugging. Also, setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU, which should be halted with pn_halt().
[in]array_sizeis the number of entries in the coremask_array.
Returns
Either PN_SUCCESS, PN_ERR_PARAM or PN_ERR_COPU.
Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

Sets the CoPUs represented by bitmask and their position in the array (= their group number) into a halted state (Mode 0).

See documentation of Modes for more information.

Cannot be executed on CoPU.

Halting an already halted core results in failure (PN_ERR_PARAM) to aid debugging.

Parameters
[in]coremask_arrayis a pointer to the start of a coremask array. The position of the mask in the array represents the group number of the cores. When all bits are set to 0, this function will return an error (PN_ERR_PARAM) to aid debugging. Also, setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU, which should be halted with pn_halt().
[in]array_sizeis the number of entries in the coremask_array.
Returns
Either PN_SUCCESS, PN_ERR_PARAM or PN_ERR_COPU.

◆ pn_halt_CoPU_m()

int pn_halt_CoPU_m ( PN_CMSK  coremask)

Halts one or more CoPUs.

Sets the CoPUs represented in the bitmask into a halted state (Mode 0).

See documentation of Modes for more information.

Cannot be executed on CoPU.

Halting an already halted core results in failure (PN_ERR_PARAM) to aid debugging.

Parameters
[in]coremaskis the bitmask representing the CoPUs you want to halt. When all bits are set to 0, this function will return an error (PN_ERR_PARAM) to aid debugging. Also, setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU, which should be halted with pn_halt().
Returns
Either PN_SUCCESS, PN_ERR_PARAM or PN_ERR_COPU.

◆ pn_m2cap()

PN_CMSK pn_m2cap ( void  )

Check which cores are capable of Mode 2 operation.

See documentation of Modes for more information.

Cannot be called from CoPU.

Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 2.

◆ pn_m2cap_g()

PN_CMSK pn_m2cap_g ( PN_NUMG  groupnum)

Check which cores are capable of Mode 2 operation.

Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

See documentation of Modes for more information.

Cannot be called from CoPU.

Parameters
[in]groupnumis the group of cores you want to know about.
Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 2.
Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

See documentation of Modes for more information.

Cannot be called from CoPU.

Parameters
[in]groupnumis the group of cores you want to know about.
Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 2.
Todo:
Group function implementation.

◆ pn_m3cap()

PN_CMSK pn_m3cap ( void  )

Check which cores are capable of Mode 3 operation.

Attention
This function will, in the current ParaNut implementation, return a hard coded 1 or PN_ERR_COPU if executed on CoPU. The reason for this is that only the CePU is capable of Mode 3.

See documentation of Modes for more information.

Cannot be called from CoPU.

Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 3.
Todo:
If other cores are ever capable of Mode 3 (and if there ever is a register to get the information from), implement this properly.

◆ pn_m3cap_g()

PN_CMSK pn_m3cap_g ( PN_NUMG  groupnum)

Check which cores are capable of Mode 3 operation.

Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

See documentation of Modes for more information.

Cannot be called from CoPU.

Parameters
[in]groupnumis the group of cores you want to know about.
Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 3.
Todo:
Currently only a stub. Will therefore always return either PN_ERR_COPU or PN_ERR_NOIMP if executed on CePU.

See documentation of Modes for more information.

Cannot be called from CoPU.

Parameters
[in]groupnumis the group of cores you want to know about.
Returns
A bitmask representing your ParaNut cores or PN_ERR_COPU. If a bit is set to 1, it means that the core is capable of operating in Mode 3.
Todo:
Group function implementation.

◆ pn_numcores()

PN_NUMC pn_numcores ( void  )

Get the number of cores in your system.

Cannot be called from CoPU.

Returns
The number of cores in your ParaNut implementation or PN_ERR_COPU.

◆ pn_simulation()

int pn_simulation ( void  )

Checks if we run in simulation instead of real hardware.

Warning
This function is a thing that only works with our specific ParaNut simulation. If the simulation changes, this needs to be changed, too.
Returns
Zero if we run on hardware, non-zero if we run in simulation.

◆ pn_time_ns()

long long int pn_time_ns ( void  )

Returns system time in ns. Does not care for overflow.

Cannot be executed on CoPU.

The first time executing this function takes the longest time since it has to initialize the frequency and an internal conversion factor. So if you want to use it for time measurement, you can call the function once before actual measurement to make the values more comparable.

When testing on my ParaNut, this made a difference of around 2000 ticks.

Returns
System time in ns or PN_ERR_COPU.

◆ pn_timebase_us()

unsigned int pn_timebase_us ( void  )

Returns machine timer timebase in us.

Returns the value of the paranut pntimebase register which should contain the current machine timer timebase in us.

Returns
Machine timer timebase in us.