Main structure, binding all components together. More...

Public Member Functions
FUNCTION_CDECL_AS_ZSTRING_PTR()	setPin (BYVAL_AS_Pruio__PTR Top, BYVAL_AS_UInt8 Ball, BYVAL_AS_UInt8 Mo)
	Interface for pinmuxing function (internal). More...

	PruIo (BYVAL_AS_UInt16, BYVAL_AS_UInt8, BYVAL_AS_UInt32, BYVAL_AS_UInt8)
	Constructor, initialize subsystems, create default configuration. More...

	~PruIo ()
	Destructor to restore configurations and clear memory. More...

FUNCTION_CDECL_AS_ZSTRING_PTR	config (BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt16)
	Load configuration from host (ARM) to driver (PRU). More...

FUNCTION_CDECL_AS_ZSTRING_PTR	Pin (BYVAL_AS_UInt8, BYVAL_AS_UInt8)
	Create a text description for a CPU ball configuration. More...

FUNCTION_CDECL_AS_ZSTRING_PTR	nameBall (BYVAL_AS_UInt8)
	Get header pin connected to CPU ball. More...

FUNCTION_CDECL_AS_ZSTRING_PTR	rb_start ()
	Start ring buffer mode. More...

FUNCTION_CDECL_AS_ZSTRING_PTR	mm_start (BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt32, BYVAL_AS_UInt32)
	Start a measurement in MM. More...

Public Attributes
ZSTRING_PTR	Errr = 0
	Pointer for error messages, see chapter Messages.

AdcUdt_PTR	Adc
	Pointer to AdcUdt class.

GpioUdt_PTR	Gpio
	Pointer to GpioUdt class.

PwmssUdt_PTR	PwmSS
	Pointer to PwmssUdt class.

TimerUdt_PTR	TimSS
	Pointer to TimerUdt class.

PwmMod_PTR	Pwm
	Pointer to PwmMod class for PWM features (in PWMSS subsystems).

CapMod_PTR	Cap
	Pointer to CapMod class for CAP features (in PWMSS subsystems).

QepMod_PTR	Qep
	Pointer to QepMod class for QEP features (in PWMSS subsystems).

TimerUdt_PTR	Tim
	Pointer to TimerUdt class for TIMER features (for homogenous API).

UInt32_PTR	DRam
	Pointer to access PRU DRam, see chapter Memory Organisation.

BallSet_PTR	Init
	The subsystems register data at start-up (to restore when finished).

BallSet_PTR	Conf
	The subsystems register data used by libpruio (current local data to be uploaded by PruIo::Config() ).

ANY_PTR	ERam
	Pointer to read PRU external ram, see chapter Memory Organisation.

ANY_PTR	DInit
	Pointer to block of subsystems initial data.

ANY_PTR	DConf
	Pointer to block of subsystems configuration data.

ANY_PTR	MOffs
	Configuration offset for modules.

UInt8_PTR	BallInit
	Pointer for original Ball configuration.

UInt8_PTR	BallConf
	Pointer to ball configuration (CPU pin muxing).

UInt32	EAddr
	The address of the external memory (PRUSS-DDR).

UInt32	ESize
	The size of the external memory (PRUSS-DDR).

UInt32	DSize
	The size of a data block (DInit or DConf).

UInt32	PruNo
	The PRU number to use (defaults to 1).

UInt32	PruIRam
	The PRU instruction ram to load.

UInt32	PruDRam
	The PRU data ram.

UInt32	PruIntNo
	The PRU interrupt number.

Int16	ParOffs
	The offset for the parameters of a module.

Int16	DevAct
	Active subsystems.

UInt32	BbType
	Type of Beaglebone board (2 = Blue, 1 = Pocket, 0 = others)

UInt32	MuxFnr
	Pinmuxing file number, if any.

ZSTRING_PTR	MuxAcc
	Pinmuxing ocp path, if no LKM.

UInt8	BallGpio [PRUIO_AZ_BALL+1]
	list of GPIO numbers, corresponding to ball index More...

tpruss_intc_initdata_PTR	IntcInit = @DEF_INTC_INIT
	interrupt settings

UInt32	WaitCycles
	Counter: ARM waiting for PRU.

Detailed Description

Main structure, binding all components together.

This UDT glues all together. It downloads and start software on the PRUSS, controls the initialisation and configuration processes and reads or writes the pinmux configurations.

Since: 0.0

Definition at line 138 of file pruio.bi.

Constructor & Destructor Documentation

◆ PruIo()

PruIo::PruIo	(	BYVAL_AS_UInt16	Act = `PRUIO_DEF_ACTIVE`,
		BYVAL_AS_UInt8	Av = `PRUIO_DEF_AVRAGE`,
		BYVAL_AS_UInt32	OpD = `PRUIO_DEF_ODELAY`,
		BYVAL_AS_UInt8	SaD = `PRUIO_DEF_SDELAY`
	)

Constructor, initialize subsystems, create default configuration.

Parameters

Act	Mask to specify active subsystems (defaults to all active).
Av	Avaraging for default steps (0 to 16, defaults to 0).
OpD	Open delay for default steps (0 to 0x3FFFF, defaults to 0x98)
SaD	Sample delay for default steps (0 to 255, defaults to 0).

The constructor tries to

open the PRUSS interrupt (/dev/uio5),
load the pasm_init.p instructions to the PRU and executes them, and
call the initialize functions of the subsystem UDTs.

It reports a failure by setting the member variable PruIo::Errr to an appropriate text (the destructor PruIo::~PruIo() should be called in that case).

Otherwise (PruIo::Errr = 0) the constructor tries to enable the subsystems and read their configurations. This gets done for the active subsystems only. Use bitmask parameter Act to specify active systems and the PRU number to run the software. For convenience, use enumerators defined in ActivateDevice:

Bit	Function	Enum default
0	0 = PRU-0, 1 = PRU-1	PRUIO_ACT_PRU1
1	ADC: 0 = inactiv, 1 = active	PRUIO_ACT_ADC
2	GPIO-0: 0 = inactiv, 1 = active	PRUIO_ACT_GPIO0
3	GPIO-1: 0 = inactiv, 1 = active	PRUIO_ACT_GPIO1
4	GPIO-2: 0 = inactiv, 1 = active	PRUIO_ACT_GPIO2
5	GPIO-3: 0 = inactiv, 1 = active	PRUIO_ACT_GPIO3
6	PWMSS-0: 0 = inactiv, 1 = active	PRUIO_ACT_PWM0
7	PWMSS-1: 0 = inactiv, 1 = active	PRUIO_ACT_PWM1
8	PWMSS-2: 0 = inactiv, 1 = active	PRUIO_ACT_PWM2
9	TIMER-4: 0 = inactiv, 1 = active	PRUIO_ACT_TIM4
10	TIMER-5: 0 = inactiv, 1 = active	PRUIO_ACT_TIM5
11	TIMER-6: 0 = inactiv, 1 = active	PRUIO_ACT_TIM6
12	TIMER-7: 0 = inactiv, 1 = active	PRUIO_ACT_TIM7
15	free pinmuxing active	PRUIO_ACT_FREMUX

By default all subsystems are activated (a subsystem has to be active before it can get disabled), and free pinmuxing is disabled.

The first bit desides which PRU to use. By default PRU-1 is used, so that PRU-0 is free for other software.

Note: libpruio always uses ARM_PRU1_INTERRUPT on channel PRU_EVTOUT_5 to trigger a measurement in RB or MM mode, even if it's running on PRU-0. So when you execute further software on the other PRU, you should use ARM_PRU0_INTERRUPT on any other channel (ie. PRU_EVTOUT_0) to notify this code, and test for R31.t30.

The other parameters Av, OpD and SaD are used to create a default step configuration for analog input. They get passed to function AdcUdt::initialize() to generate default step configuration data for all analog lines (AIN-0 to AIN-7) in the steps 1 to 8. For these steps, the default values can get customized using the (optional) parameter list:

parameter Av sets avaraging in a certain number of steps. Options are 1, 2, 4, 8 or 16. (A non-matching parameter get increased either to the next higher or to the last option.)
parameter OpD sets the open delay, which is the number of clock cycles the ADC waits between setting the step configuration and sending the start of conversion signal.
parameter SaD sets the sample delay, which is the number of clock cycles the ADC waits before starting (the width of the start of conversion signal). It specifies the number of clock cycles between the single conversion processes.

See ARM Reference Guide, chapter 12 for details on step configuration.

These step configurations can get customized or extended later on by calling function AdcUdt::setStep().

Wrapper function (C or Python): pruio_new().

Since: 0.0

Definition at line 146 of file pruio.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ~PruIo()

PruIo::~PruIo ( )

Destructor to restore configurations and clear memory.

The destructor copies the original configuration to DRam (if any), loads new instructions to the PRU and start them. This PRU code restores the subsystems GPIOs, Control Module and ADC to their original configurations. Finaly the PRU gets powered off and the memory of the PruIo instance get freed.

The destructor cannot report error messages in member variable PruIo::Errr. Messages (if any) get sent directly to the ERROUT pipe of the operating system instead.

Wrapper function (C or Python): pruio_destroy().

Since: 0.0

Definition at line 284 of file pruio.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ config()

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::config	(	BYVAL_AS_UInt32	Samp = `PRUIO_DEF_SAMPLS`,
		BYVAL_AS_UInt32	Mask = `PRUIO_DEF_STPMSK`,
		BYVAL_AS_UInt32	Tmr = `PRUIO_DEF_TIMERV`,
		BYVAL_AS_UInt16	Mds = `PRUIO_DEF_LSLMOD`
	)

Load configuration from host (ARM) to driver (PRU).

Parameters

Samp	Number of samples to fetch (defaults to 1).
Mask	Mask for active ADC steps (defaults to all 8 channels active in steps 1 to 8).
Tmr	Timer value in [ns] to specify the sampling rate (defaults to zero, MM and RB mode only).
Mds	Modus for output (defaults to 4 = 16 bit).

Returns: Zero on success (otherwise a string with an error message).

This function is used to download the configuration from the host (ARM) to the driver (PRU). The PRU gets stopped (if running) and the new configurations get loaded. Also the Pru_Run instructions get re-initialized.

In case of an error the PRU will be disabled after this call. Otherwise it

is running and waits for a call to PruIo::mm_start() or PruIo::rb_start() (in case of Samp > 1), or
it starts sampling immediately and feads values to AdcUdt::Value otherwise (Samp = 1).
it halts after loading the local configuration to the subsystem registers (Samp = 0).

The Samp parameter specifies the run mode (IO, RB or MM) and the number of samples to convert for each step. In IO mode (Samp = 1, default) sampling starts immediately and the index in the array AdcUdt::Value[] is equal to the step number. Inactive steps return 0 (zero) in this case.

field	result of	defaults to
Value[0]	charge step	allways zero
Value[1]	step 1	AIN-0
Value[2]	step 2	AIN-1
...	...	...
Value[8]	step 8	AIN-7
Value[9]	step 9	undefined
...	...	...
Value[16]	step 16	undefined

In MM (Samp > 1) the array AdcUdt::Value[] contains no zero values. Instead only values from active steps get collected. The charge step (step 0) returns no value. So when 3 steps are active in the Mask and Samp is set to 5, a total of 3 times 5 = 15 values get available in the array AdcUdt::Value[] (after the call to function PruIo::mm_start() ). The array contains the active steps, so when ie. steps 3, 6 and 7 are active in the Mask, the array contains:

field	Mask = &b110010000
Value[0]	1. sample AIN-3
Value[1]	1. sample AIN-6
Value[2]	1. sample AIN-7
Value[3]	2. sample AIN-3
Value[4]	2. sample AIN-6
Value[5]	2. sample AIN-7
Value[6]	3. sample AIN-3
Value[7]	3. sample AIN-6
Value[8]	...

Currently the number of samples is limited by the external memory allocated by the kernel PRUSS driver. This is 256 kByte by default (= 128 kSamples, see next table). Find informations on how to extend this memory block in section ERam.

number of active Steps	max. Samples
1	131072
2	65536
3	43690
4	32768
5	26214
6	21845
7	18724
8	16384
...	...

The Mask parameter specifies the active steps. Setting a bit in the Mask activates a step defined by the step configuration (by default bits 1 = AIN-0, 2 = AIN-1, ... up to 8 = AIN-7 are set, use function AdcUdt::setStep() to customize steps).

Note: Bit 0 controls the charge step (see ARM Reference Guide, chapter 12, ADC STEPENABLE register).

The highest bit 31 has a special meaning for customizing the idle step. By default the idle configuration is set like the configuration of the first active step, so that (in MM) the open delay can get reduced to a minimum for that step (if there's enough time left before restarting the ADC). By setting bit 31 the configuration from AdcUdt::Conf->St_p[0] is used instead.

The Tmr parameter specifies the sampling rate. It's the number of nano seconds between the starts of the ADC sampling process. The IEP timer gets used. It is configured to increase by steps of 5 (it counts in GHz, but runs at 200 MHz), so values like 22676 or 22679 results to the same frequency. Some examples

Tmr [ns]	Sampling rate [Hz]
1e9	1
1e6	1000
22675	~44100

Note: This value has no effect in IO mode (when Samp = 1).

The Mds parameter specifies the bit encoding (range) of the samples. By default (Mds = 4) the samples from the ADC (12 bit) get left shifted by 4, so that they actually are 16 bit values and can get compared with samples from other ADC devices (like 16 bit audio data). Examples

Mds	samples
0	12 bit
1	13 bit
2	14 bit
3	15 bit
>= 4	16 bit

Wrapper function (C or Python): pruio_config().

Since: 0.0

Definition at line 452 of file pruio.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mm_start()

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::mm_start	(	BYVAL_AS_UInt32	Trg1 = `0`,
		BYVAL_AS_UInt32	Trg2 = `0`,
		BYVAL_AS_UInt32	Trg3 = `0`,
		BYVAL_AS_UInt32	Trg4 = `0`
	)

Start a measurement in MM.

Parameters

Trg1	Specification for first trigger (default = no trigger).
Trg2	Specification for second trigger (default = no trigger).
Trg3	Specification for third trigger (default = no trigger).
Trg4	Specification for fourth trigger (default = no trigger).

Returns: Zero on success (otherwise a string with an error message).

This function starts a measurement in MM mode. The ADC configuration from the previous call to function PruIo::config() are used. The measurement either starts immediately or the start gets controlled by one (or up to four) trigger event(s).

Function are available to create trigger specifications:

AdcUdt::mm_trg_pin() for digital lines
AdcUdt::mm_trg_ain() for analog lines
AdcUdt::mm_trg_pre() for pre-triggers on analog lines

Note: The created analog trigger specifications may get invalid by changing the ADC settings in a further call to function PruIo::config() with different parameters (ie. when the trigger step gets cleared). To be on the save side, re-create your trigger specifications after each call to function PruIo::config().

MM mode runs endless. Stop it by up-loading a new configuration (by calling function PruIo::config() ).

Wrapper function (C or Python): pruio_mm_start().

Since: 0.2

Definition at line 684 of file pruio.bas.

◆ nameBall()

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::nameBall ( BYVAL_AS_UInt8 Ball )

Get header pin connected to CPU ball.

Parameters

Ball	The CPU ball number.

Returns: A string pointer (don't free it) on success (otherwise zero).

This function creates a text description of the header pin connected to a CPU ball. The returned string is owned by this function and must not be freed.

When the CPU ball is not connected to a header pin, this function returns 0 (zero).

Note: Since 0.6.8 also Pocket and Blue names are implemented.

Since: 0.2

Definition at line 592 of file pruio.bas.

Here is the caller graph for this function:

◆ Pin()

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::Pin	(	BYVAL_AS_UInt8	Ball,
		BYVAL_AS_UInt8	Mo = `1`
	)

Create a text description for a CPU ball configuration.

Parameters

Ball	The CPU ball number to describe.
Mo	The configuration to read (0 = Init, else Conf = default).

Returns: A human-readable text string (internal string, never free it).

This function is used to create a text description for the current state of a CPU ball (named pin when connected to one of the Beaglebone headers P8 or P9).

The description contains the pin name and its mode. Header pin names start with a capital 'P', CPU ball names start with a lower case 'b'. The detailed pinmux setting is only described for pins in mode 7 (GPIO mode). Otherwise only the mode number gets shown.

Note: The returned string pointer points to an internal string buffer. Never free it. The string gets overwritten on further calls to this function, so make local copies if you need several descriptions at a time. The string may contain an error message if the ball number is too big.

Since: 0.2

Definition at line 506 of file pruio.bas.

Here is the call graph for this function:

◆ rb_start()

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::rb_start ( )

Start ring buffer mode.

Returns: Zero on success (otherwise a string with an error message).

Start endless measuremnt in ring buffer mode. The active steps defined in the last call to function PruIo::config() get sampled at the specified sampling rate. The fetched values are stored in a ring buffer and the index of the currently stored value gets reported in DRam[0].

Inactive steps get no entry in the ring buffer, it only contains values from the active steps (as in MM mode). Use AdcUdt::Value[index] to read the samples.

RB mode runs endless. Stop it by up-loading a new configuration (by calling function PruIo::config() ).

Wrapper function (C or Python): pruio_rb_start().

Since: 0.2

Definition at line 638 of file pruio.bas.

◆ setPin()

FUNCTION_CDECL_AS_ZSTRING_PTR() PruIo::setPin	(	BYVAL_AS_Pruio__PTR	Top,
		BYVAL_AS_UInt8	Ball,
		BYVAL_AS_UInt8	Mo
	)

Interface for pinmuxing function (internal).

Parameters

Top	The toplevel PruIo instance.
Ball	The CPU ball number (use macros from pruio_pins.bi).
Mo	The new modus to set.

Returns: Zero on success (otherwise a string with an error message).

This is an internal function. It tries to set a new mode for a header pin (or CPU ball number) configuration. Each digital header pin is connected to a CPU ball. The CPU ball can get muxed to

several internal features (like GPIO, CAP, PWM, ...),
internal pullup or pulldown resistors, as well as
an internal receiver module for input pins.

The function changes pinmuxing, and will fail if (depending on system setup):

the libpruio loadable kernel module isn't loaded, or
the libpruio device tree overlays isn't loaded, or
the required pin isn't defined in that overlay (ie HDMI), or
the user has no write access to the state configuration files (see section Pinmuxing for details), or
the required mode isn't available in the overlay.

The function returns an error message in case of a failure, otherwise 0 (zero). The callback function gets connected in the constructor PruIo::PruIo(), depending on the system setup and current write privileges. The prefered method is the LKM method, which is used when the SysFs entry from the LKM is present, and libpruio has write access (needs administrator privileges = sudo ... or membership in user group 'pruio'). Otherwise the old-style device tree pinmuxing gets used, if present.

In case of LKM pinmuxing there're no restriction. Each CPU ball in the range zero to PRUIO_AZ_BALL can get set to any mode. Even claimed pins or CPU balls can get set to defined or undefined modes. The function executes faster than device tree pinmuxing (no OPEN ... CLOSE), boot-time is shorter (no overlay loading) and less memory is used.

Note: Don't use this function to set a pin for a libpruio feature. Instead, call for input pins the feature config function (ie. GpioUdt::config() or CapMod::config() ), and for output pins just set the desired value (ie. PwmMod::setValue()). But you can use the function to set pins in modes that are not supported by libpruio (ie. like SPI or UART). In this case you have to care about loading the matching driver by yourself.; In case of digital double pins (like P9_41 or P9_42 on BeagleBone) this function sets the muxmodes of boths pins. First the unused pin gets configured to Gpio input mode without resistor. Then the related pin gets configured as specified.

Since: 0.6

Here is the caller graph for this function:

Member Data Documentation

◆ BallGpio

UInt8 PruIo::BallGpio[PRUIO_AZ_BALL+1]

Initial value:

= { 
     32,  33,  34,  35,  36,   37,  38,  39,  22,  23 
  ,  26,  27,  44,  45,  46,   47,  48,  49,  50,  51 
  ,  52,  53,  54,  55,  56,   57,  58,  59,  30,  31 
  ,  60,  61,  62,  63,  64,   65,  66,  67,  68,  69 
  ,  70,  71,  72,  73,  74,   75,  76,  77,  78,  79 
  ,  80,  81,   8,   9,  10,   11,  86,  87,  88,  89 
  ,  90,  91,  92,  93,  94,   95,  96,  97,  98,  99 
  , 100,  16,  17,  21,  28,  105, 106,  82,  83,  84 
  ,  85,  29,   0,   1,   2,    3,   4,   5,   6,   7 
  ,  40,  41,  42,  43,  12,   13,  14,  15, 101, 102 
  , 110, 111, 112, 113, 114,  115, 116, 117,  19,  20}

list of GPIO numbers, corresponding to ball index

Definition at line 238 of file pruio.bi.

The documentation for this class was generated from the following files:

src/pruio/pruio.bi
src/pruio/pruio.bas

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PruIo()

◆ ~PruIo()

Member Function Documentation

◆ config()

◆ mm_start()

◆ nameBall()

◆ Pin()

◆ rb_start()

◆ setPin()

Member Data Documentation

◆ BallGpio