libparanut
A Hardware Abstraction Layer for ParaNut Architectures.
Thread Module

Functions for using the threaded mode. More...

Collaboration diagram for Thread Module:
void pn_thread_entry (void)
 Function that has to be called for CoPUs at the end of the startup code. More...
 
PN_CID pn_begin_threaded (PN_NUMC numcores)
 Puts numcores CPUs in threaded mode. More...
 
PN_CID pn_begin_threaded_m (PN_CMSK coremask)
 Puts the CPUs specified in the coremask in threaded mode. More...
 
PN_CID pn_begin_threaded_gm (PN_CMSK *coremask_array, PN_NUMG array_size)
 Puts the CPUs specified in the coremask_array in threaded mode. More...
 
int pn_end_threaded (void)
 Ends threaded execution. More...
 
PN_CMSK pn_run_threaded (PN_NUMC numcores, void(*function)(void *args, PN_CID cid), void *args)
 Excutes a given function on the CoPUs specified in numcores. More...
 
PN_CMSK pn_join_thread_m (PN_CMSK coremask, uint32_t timeout)
 Waits until a specified set of CePUs is stopped. More...
 

Detailed Description

Functions for using the threaded mode.

Also see Modes.

Function Documentation

◆ pn_begin_threaded()

PN_CID pn_begin_threaded ( PN_NUMC  numcores)

Puts numcores CPUs in threaded mode.

Todo:
Not yet implemented for more cores than what is available in one group. Will return PN_ERR_NOIMP when called with more cores.

Sets numcores-1 CoPUs to Mode 2 (unlinked Mode) so they start executing the following code in parallel. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions, until pn_end_threaded() is called.

Attention
All data that you want to preserve after pn_end_threaded() was called can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
Parameters
[in]numcoresis the number of cores that shall run threaded. A value of 0 or 1 will return an error (PN_ERR_PARAM) to aid debugging.
Returns
The ID of the core, or PN_ERR_MATCH, PN_ERR_PARAM, or PN_ERR_COPU.
Todo:
Not yet implemented for more cores than what is available in one group. Will return PN_ERR_NOIMP when called with more cores.

Sets numcores-1 CoPUs to Mode 2 (unlinked Mode) so they start executing the following code in parallel. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions, until pn_end_threaded() is called.

Attention
All data that you want to preserve after pn_end_threaded() was called can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
Parameters
[in]numcoresis the number of cores that shall run threaded. A value of 0 or 1 will return an error (PN_ERR_PARAM) to aid debugging.
Returns
The ID of the core, or PN_ERR_MATCH, PN_ERR_PARAM, or PN_ERR_COPU.

◆ pn_begin_threaded_gm()

PN_CID pn_begin_threaded_gm ( PN_CMSK coremask_array,
PN_NUMG  array_size 
)

Puts the CPUs specified in the coremask_array in threaded mode.

Todo:
Currently only a stub. Will therefore always return PN_ERR_NOIMP.

Sets the CoPUs represented by bitmask and their position in the array (= their group number) to Mode 2 (unlinked Mode) so they start executing the following code in parallel. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions, until pn_end_threaded() is called.

Attention
All data that you want to preserve after pn_end_threaded() was called can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
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, not setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU (which needs to run threaded, too).
[in]array_sizeis the number of entries in the coremask_array.
Returns
The ID of the core, or PN_ERR_MATCH, PN_ERR_PARAM, or PN_ERR_COPU.
Todo:
Currently only a stub. Will therefore always return PN_ERR_NOIMP.

Sets the CoPUs represented by bitmask and their position in the array (= their group number) to Mode 2 (unlinked Mode) so they start executing the following code in parallel. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions, until pn_end_threaded() is called.

Attention
All data that you want to preserve after pn_end_threaded() was called can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
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, not setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU (which needs to run threaded, too).
[in]array_sizeis the number of entries in the coremask_array.
Returns
The ID of the core, or PN_ERR_MATCH, PN_ERR_PARAM, or PN_ERR_COPU.

◆ pn_begin_threaded_m()

PN_CID pn_begin_threaded_m ( PN_CMSK  coremask)

Puts the CPUs specified in the coremask in threaded mode.

Sets the CoPUs represented by the bitmask to Mode 2 (unlinked Mode) so they start executing the following code in parallel. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions, until pn_end_threaded() is called.

Attention
All data that you want to preserve after pn_end_threaded() was called can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
Parameters
[in]coremaskis the bitmask representing the CoPUs you want to run threaded. When all bits are set to 0, this function will return an error (PN_ERR_PARAM) to aid debugging. Also, not setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU (which needs to run threaded, too).
Returns
The ID of the core, or PN_ERR_MATCH, PN_ERR_PARAM, or PN_ERR_COPU.

◆ pn_end_threaded()

int pn_end_threaded ( void  )

Ends threaded execution.

On CoPU, halts the core. On CePU, waits until all other cores are halted. This ends the threaded mode.

See documentation of Modes for more information.

Returns
Either PN_SUCCESS or PN_ERR_MATCH.

◆ pn_join_thread_m()

PN_CMSK pn_join_thread_m ( PN_CMSK  coremask,
uint32_t  timeout 
)

Waits until a specified set of CePUs is stopped.

Wait a maximum of timeout ms for CePUs defined in coremask to be stopped. If the timeout is exceeded, the CePUs ARE NOT FORCED TO STOP. If this behaviour is desired, it must be implemented in the calling function (e.g. add a pn_end_threaded) to the next line. Timeout may be 0, meaning the function will run indefinatly

Attention
This is a blocking function. It is strongly advised always to specify a timeout.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
Parameters
[in]coremaskis the bitmask representing the CoPUs you want to run threaded. When all bits are set to 0, this function will return an error (PN_ERR_PARAM) to aid debugging. Also, not setting the first bit to 1 will return an error (PN_ERR_PARAM) since it represents the CePU (which needs to run threaded, too).
Returns
The ID of the core(s) stopped, or PN_ERR_COPU.

◆ pn_run_threaded()

PN_CMSK pn_run_threaded ( PN_NUMC  numcores,
void(*)(void *args, PN_CID cid)  function,
void *  args 
)

Excutes a given function on the CoPUs specified in numcores.

Sets numcores-1 CoPUs to Mode 2 (unlinked Mode) they then start execting the function provided and halt once completed. This function will return an error (PN_ERR_MATCH) if the CoPUs are not all halted.

See documentation of Modes for more information.

Cannot be executed on CoPU. Cannot be mixed with linked mode or other begin threaded functions. The calling CePU is not informed when the function has finished execution. This can be accomplished by monitoring the state of CePUs marked in the numcores

Attention
All data that you want to preserve can not be stored on stack. You can make it static or global.
Warning
There is no guarantee that the execution of code actually happens at the same time on CePUs and CoPUs.
Parameters
[in]numcoresis the number of cores that shall run the function. A value of 0 or 1 will return an error (PN_ERR_PARAM) to aid debugging.
[in]functionpointer to a function, which will be used as entrypoint for the started CoPUs. The function must define two parameters: void *args - void pointer to hand arguments to the function PN_CID cid - core id of the core executing the function
[in]argspointer of type void, that may be used to add arguments to the function called. This parameter may be of value NULL.
Returns
A mask representing the CePUs started by this functioncall

◆ pn_thread_entry()

void pn_thread_entry ( void  )

Function that has to be called for CoPUs at the end of the startup code.

Marks the entry point of CoPUs into the Thread Module. Necessary for threaded Mode.

The CoPUs are set up to work correctly in threaded Mode.

Execution is only effective on CoPU. Can be executed on CePU, will do nothing then.

Should not be called in a normal application at all. Left in here for startup code writers convenience.

Attention
What comes after this part in the startup code is irrelevant, since the CoPUs that landed there are either put into threaded mode or halted. The function can therefore not return any errors.