All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
PruIo Class Reference

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

## Public Member Functions

| 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_UInt32)
| Create a text description for a CPU ball configuration. More...
FUNCTION_CDECL_AS_ZSTRING_PTR | setPin (BYVAL_AS_UInt8, BYVAL_AS_UInt8)
| Set a new pin 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

AdcUdt_PTR | Adc
| Pointer to ADC subsystem structure.
GpioUdt_PTR | Gpio
| Pointer to GPIO subsystems structure.
PwmssUdt_PTR | PwmSS
| Pointer to PWMSS subsystems structure.
PwmMod_PTR | Pwm
| Pointer to the ePWM module structure (in PWMSS subsystems).
CapMod_PTR | Cap
| Pointer to the eCAP module structure (in PWMSS subsystems).
ZSTRING_PTR | Errr = 0
| Pointer for error messages.
UInt32_PTR | DRam
| Pointer to access PRU DRam.
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.
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 | PruEvtOut
| The interrupt channel to send commands to PRU.
UInt32 | PruIRam
| The PRU instruction ram to load.
UInt32 | PruDRam
| The PRU data ram.
INT16 | ArmPruInt
| The interrupt to send.
INT16 | ParOffs
| The offset for the parameters of a module.
INT16 | DevAct
| Active subsystems.
STRING | MuxAcc
| Path for pinmuxing.
tpruss_intc_initdata | IntcInit
| interrupt settings (we also set default interrupts, so that the other PRUSS can be used in parallel) More...
UInt8 | BallGpio [PRUIO_AZ_BALL+1]
| list of GPIO numbers, corresponding to ball index More...

## 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.

Definition at line 118 of file pruio.bi.

## Constructor & Destructor Documentation

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 structure should be freed 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 parameter Act to specify active systems and the PRU number to run the software:

Bit | Function
--- | ---
8 | PWMSS-2: 0 = inactiv, 1 = active
7 | PWMSS-1: 0 = inactiv, 1 = active
6 | PWMSS-0: 0 = inactiv, 1 = active
5 | GPIO-3: 0 = inactiv, 1 = active
4 | GPIO-2: 0 = inactiv, 1 = active
3 | GPIO-1: 0 = inactiv, 1 = active
2 | GPIO-0: 0 = inactiv, 1 = active
1 | ADC: 0 = inactiv, 1 = active
0 | 0 = PRU-0, 1 = PRU-1

For convenience, use enumerators PruIo::ActivateDevice. By default all subsystems are activated. (A subsystem has to be active before it can get disabled.)

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 generates 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().

Definition at line 190 of file pruio.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Definition at line 295 of file pruio.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

## Member Function Documentation

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 zero).
  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 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's 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.

The Samp parameter specifies the number of samples to convert for each channel. In single mode (Samp <= 1 = default) sampling starts immediately and the index in the array PruIo::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
... | ... | ...

In MM (Samp > 1) the array PruIo::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 ChaMemory for informations on how to extend this memory block.

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 single mode (when Samp is less than 2).

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

Definition at line 450 of file pruio.bas.

Here is the caller graph for this function:

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() ).

Definition at line 742 of file pruio.bas.

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).

Since
  0.2

Definition at line 610 of file pruio.bas.

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::Pin | ( | BYVAL_AS_UInt8 | Ball,
|  | BYVAL_AS_UInt32 | Mo = `0`
| ) |  |

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).

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 (called a pin when it's 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.

Definition at line 504 of file pruio.bas.

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() ).

Definition at line 699 of file pruio.bas.

FUNCTION_CDECL_AS_ZSTRING_PTR PruIo::setPin | ( | BYVAL_AS_UInt8 | Ball,
|  | BYVAL_AS_UInt8 | Mo
| ) |  |

Set a new pin configuration.

Parameters

  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 function tries to set a new header pin configuration. Each digital header pin is connected to a CPU ball. The CPU ball can get muxxed to

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

The function will fail if

- 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 SecPinmux for details), or
- the required mode isn't available in the overlay.

The function returns an error message in case of a failure.

Since
  0.2

Definition at line 571 of file pruio.bas.

Here is the caller graph for this function:

## Member Data Documentation

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 185 of file pruio.bi.

tpruss_intc_initdata PruIo::IntcInit

Initial value:
=
TYPE<tpruss_intc_initdata>(
{ PRU0_PRU1_INTERRUPT
, PRU1_PRU0_INTERRUPT
, PRU0_ARM_INTERRUPT
, PRU1_ARM_INTERRUPT
, ARM_PRU0_INTERRUPT
, ARM_PRU1_INTERRUPT
, PRUIO_IRPT
, CAST(BYTE, -1) },
{ TYPE<tsysevt_to_channel_map>(PRU0_PRU1_INTERRUPT, CHANNEL1)
, TYPE<tsysevt_to_channel_map>(PRU1_PRU0_INTERRUPT, CHANNEL0)
, TYPE<tsysevt_to_channel_map>(PRU0_ARM_INTERRUPT, CHANNEL2)
, TYPE<tsysevt_to_channel_map>(PRU1_ARM_INTERRUPT, CHANNEL3)
, TYPE<tsysevt_to_channel_map>(ARM_PRU0_INTERRUPT, CHANNEL0)
, TYPE<tsysevt_to_channel_map>(ARM_PRU1_INTERRUPT, CHANNEL1)
, TYPE<tsysevt_to_channel_map>(PRUIO_IRPT, PRUIO_CHAN)
, TYPE<tsysevt_to_channel_map>(-1, -1)},
{ TYPE<tchannel_to_host_map>(CHANNEL0, PRU0)
, TYPE<tchannel_to_host_map>(CHANNEL1, PRU1)
, TYPE<tchannel_to_host_map>(CHANNEL2, PRU_EVTOUT0)
, TYPE<tchannel_to_host_map>(CHANNEL3, PRU_EVTOUT1)
, TYPE<tchannel_to_host_map>(PRUIO_CHAN, PRUIO_EMAP)
, TYPE<tchannel_to_host_map>(-1, -1) },
(PRU0_HOSTEN_MASK OR PRU1_HOSTEN_MASK OR
PRU_EVTOUT0_HOSTEN_MASK OR PRU_EVTOUT1_HOSTEN_MASK OR PRUIO_MASK)
)

interrupt settings (we also set default interrupts, so that the other PRUSS can be used in parallel)

Definition at line 156 of file pruio.bi.

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

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