libpruio  0.6.8
Fast and easy Digital/Analog Input/Output for Beaglebones
PruIo Class Reference

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
ActMask to specify active subsystems (defaults to all active).
AvAvaraging for default steps (0 to 16, defaults to 0).
OpDOpen delay for default steps (0 to 0x3FFFF, defaults to 0x98)
SaDSample 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
SampNumber of samples to fetch (defaults to 1).
MaskMask for active ADC steps (defaults to all 8 channels active in steps 1 to 8).
TmrTimer value in [ns] to specify the sampling rate (defaults to zero, MM and RB mode only).
MdsModus 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
Trg1Specification for first trigger (default = no trigger).
Trg2Specification for second trigger (default = no trigger).
Trg3Specification for third trigger (default = no trigger).
Trg4Specification 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:

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
BallThe 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
BallThe CPU ball number to describe.
MoThe 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
TopThe toplevel PruIo instance.
BallThe CPU ball number (use macros from pruio_pins.bi).
MoThe 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: