OMAP-L1 Linux Drivers Usage

Before starting to use the drivers please read information on how to configure and rebuild the Linux kernel.

Ethernet

To test the ethernet interface, you need a valid IP address. To set a static IP address:

target$ ifconfig eth0 <static IP address>

To obtain an IP address dynamically using DHCP server on the network use:

target$ udhcpc

To test network connectivity, use ping command to the the network gateway

target$ ping <IP address of network gateway>

Audio

ALSA commands aplay and arecord can be used to playback and record audio respectively. ALSA mixer commands can be used to adjust the playback and capture volume. The command amixer contents lists all the params that can be controlled by mixer. To record and playback the content enter:

target$ arecord -f dat | aplay -f dat

To know the current volume settings enter: 
target$ amixer cget numid=1

To change the playback volume, the following command can be used

target$ amixer cset numid=1 80,80 # Sets the volume to 80
target$ amixer cset numid=2 80,80 #This is also used to adjust playback volume

Character LCD

Character LCD can be tested by writing some characters/strings to the LCD device:

target$ echo "Hello, World" > /dev/lcd

The above command will display the string "Hello, World" on the character LCD.

The LCD device can be controlled by writing the following escape sequences to the LCD device (echo <escape sequence> > /dev/lcd):

NOTE
Pressing "Ctrl-v", "Ctrl-[" on keyboard will generate the "^[" escape sequence. In some file systems, the escape sequences may not appear on the serial console but the input will still reach the character LCD.

Escape Sequence	Functionality
^[[2J	Clear the display
^[[LI	Reinitialize display
^[[H	Cursor to home
^[[LD	Display ON
^[[Ld	Display OFF
^[[LC	Cursor ON
^[[Lc	Cursor OFF
^[[LB	Blink ON
^[[Lb	Blink OFF
^[[Ll	Shift Cursor Left
^[[Lr	Shift Cursor Right
^[[LL	Shift Display Left
^[[LR	Shift Display Right

RTC

Use the hwclock utility to test RTC. The RTC device node created is /dev/rtc0

McBSP

The McBSP test setup on the EVM comprises of two EVMs connected via the audio expansion slot. One EVM will act as the master and the other as slave. There is a sample kernel module provided in the examples included in the PSP package which demonstrates the working of McBSP peripheral.

For McBSPs to be interfaced via the audio expansion slot, S7-2 should be turned ON. Note that on doing this audio will not work anymore.

Refer to the README file present with the McBSP example to know more about the module parameters that have to be passed to the sample module to configure the peripheral.

eCAP

eCAP module can function either in PWM mode or Capture mode. The current release of the driver supports only PWM mode. eCAP can be controlled from the user space through SYSFS interface.

target$cat /sys/class/pwm/ecap.i

Where,
‘i’ is the eCAP instance.

SYSFS Attributes:
(i) Request
Reading the attribute requests the device and write to the attribute frees the device. Before performing any operations, device has to be requested first..

Request the Device:
target$ echo 1 > /sys/class/pwm/ecap.i/request
free the device:
target$ echo 0 > /sys/class/pwm/ecap.i/request

(ii) run
The “run” attribute can take two values 0 and 1 .
0 –Stop pwm, 1 –Start pwm.

Once the PWM configuration is done, pwm has to be first started by writing ‘1’.

Start the PWM
target$ echo 1 > /sys/class/pwm/ecap.i/run
Stop the PWM
target$ echo 0 > /sys/class/pwm/ecap.i/run

Setting the Period
Following attributes set the period of the PWM waveform

(iii)frequency
Enter the period in HZ .Once the frequency is configured, make sure to set the duty cycle value.

target$ echo 100 > /sys/class/pwm/ecap.i/period_freq
target$ echo 50 > /sys/class/pwm/ecap.i/duty_percent

Above commands generate PWM of 100 HZ with 50 % duty cycle.

(iv) period_ns
 Enter the period in nano seconds value. For eg., if the period is 1 sec , enter

target$ echo 100000000 > /sys /class/pwm/ecap.i/period_ns

Setting the Duty
Following attributes set the duty of the PWM waveform
(v) duty_percent
  Enter the Duty cycle value in percentage. To configure for 50% duty cycle, enter

target$ echo 50 > /sys/class/pwm/ecap.i/duty_percent

(vi) duty_ns
duty_ns takes the duty cycle value in nano seconds. To configure for 0.5s, enter

target$ echo 50000000 > /sys /class/pwm/ecap.i/duty_ns

Setting the Polarity
(vii) Polarity
To set the polarity to Active High, Enter

target$ echo 1 > /sys /class/pwm/ecap.i/polarity

To set the polarity to Active Low, Enter

target$ echo 0 > /sys /class/pwm/ecap.i/polarity

Example Configuration:
Following example shows steps to configure the PWM for 100 HZ with 50% duty cycle.

target$ echo 1 > /sys/class/pwm/ecap.i/request
target$ echo 100 > /sys/class/pwm/ecap.i/period_freq
target$ echo 50 > /sys/class/pwm/ecap.i/duty_percent
target$ echo 1 > /sys/class/pwm/ecap.i/run

Note:

 To change the frequency, first stop the PWM waveform, reset the duty to zero and then follow the last 3 steps in the above Example Configuration. 

eHRPWM

eHRPWM can be used to generate effective and complex PWM waveforms. eHRPWM can be controlled from the user space through SYSFS interface.

target$ cat /sys/class/pwm/ehrpwm.i:j

Where, ‘i’ is the eHRPWM instance
'j' is the eHRPWM ouptut 0 or 1[Each instance of eHRPWM has 2 outputs]

SYSFS Attributes
i) Request
Reading the attribute requests the device and write to the attribute frees the device. Before performing any operations, device has to be requested first.

Request the Device:
target$ echo 1 > /sys/class/pwm/ehrpwm.i:j/request
free the device:
target$ echo 0 > /sys/class/pwm/ehrpwm.i:j/request

(ii) run
The “run” attribute can take two values 0 and 1 .
0 –Stop pwm, 1 –Start pwm.

Once the PWM configuration is done, pwm has to be first started by writing ‘1’.

Start the PWM
target$ echo 1 > /sys/class/pwm/ehrpwm.i.j/run
Stop the PWM
target$ echo 0 > /sys/class/pwm/ehrpwm.i.j/run

Setting the Period
Following attributes set the period of the PWM waveform
(iii) frequency
Enter the period in HZ .Once the frequency is configured, make sure to set the duty cycle value.

target$ echo 100 > sys/class/pwm/ehrpwm.i:j/period_freq
target$ echo 50 > /sys/class/pwm/ehrpwm.i:j/duty_percent

Above commands generate PWM of 100 HZ with 50 % duty cycle.
(iv) period_ns
Enter the period in nano seconds value. For eg., if the period is 1 sec , enter

target$ echo 100000000 > /sys/class/pwm/ehrpwm.i:j/period_ns

Setting the Duty
Following attributes set the duty of the PWM waveform
(v) duty_percent
Enter the Duty cycle value in percentage. To configure for 50% duty cycle, enter

target$ echo 50 > /sys/class/pwm/ehrpwm.i:j/duty_percent

(vi) duty_ns
duty_ns takes the duty cycle value in nano seconds. To configure for 0.5s, enter

target$ echo 50000000 > /sys/class/pwm/ehrpwm.i:j/duty_ns

Setting the Polarity
(vii) Polarity
To set the polarity to Active High, Enter

target$ echo 1 > /sys/class/pwm/ehrpwm.i:j/polarity

To set the polarity to Active Low, Enter

target$ echo 0 > /sys/class/pwm/ehrpwm.i:j/polarity

Example Configuration:
Following example shows steps to configure the PWM for 100 HZ with 50% duty cycle.

target$ echo 1 > /sys/class/pwm/ehrpwm.i:j/request
target$ echo 100 > /sys/class/pwm/ehrpwm.i:j/frequency
target$ echo 50 > /sys/class/pwm/ehrpwm.i:j/duty_percent
target$ echo 1 > /sys/class/pwm/ehrpwm.i:j/run

Note:
To change the frequency, first stop the PWM waveform, reset the duty to zero and then follow the last 3 steps in the above Example Configuration.

eCAP Capture

This section describes the procedure to test eCAP capture driver. eCAP capture driver is accessible in user space thorough sysfs interface.

target$cat /sys/class/pwm/ecap_cap.i

Where,
‘i’ is the eCAP instance.

• Configuration

Before performing any operation, device has to be configured first.

target$ cat /sys/class/pwm/ecap_cap.i/config

Will return 0 on success.

• Computing frequency

target$ cat /sys/class/pwm/ecap_cap.i/freq

Returns 3 frequencies on success and -1 on failure.

   ----       ----       ----       ----
  |    |     |    |     |    |     |
__|    |_____|    |____ |    |____ |  
  |          |          |          |   
  |-1st freq-|-2nd freq-|-3rd freq-|
  |          |          |          |
  

Prerequisite: PWM whose frequency needs to be computed has to be given as an input to the corresponding pin.

• Computing duty cycle

target$ cat /sys/class/pwm/ecap_cap.i/duty_percentage

Returns duty cycle in % on success and -1 on failure.

Power Management

CPUFreq

The cpufreq driver in kernel allows scaling of clock speed of the CPU on the fly to save power. CPU consumes lower power at lower frequencies.

Please see CPUFreq User's Guide for a comprehensive list of supported features.

Operating point

An operating point is a voltage frequency pair that defines a specific power state that the SoC has been characterized for. To see the list of available OPPs (frequencies):

target$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
300000 200000 96000
target$ 

NOTE
From 03.21.00.04 release onwards, the range of operating points available depends on the "maxcpuclk" environment variable which can be set from U-Boot. For example, to set the maximum possible frequency which can be set from Linux, to 456 MHz, set "maxcpuclk" from U-Boot as below:

u-boot> setenv maxcpuclk 456000000

Note that setting the "maxcpuclk" to 456 MHz, as shown above will not set the frequency to 456 MHz. Operating points supported in Linux are: 456 MHz, 408 MHz, 372 MHz, 300 MHz, 200 MHz and 96 MHz.

Governors

CPUfreq governor is responsible to making the decision on the OPP to be used among the available OPPs. You can change the governor being used using sysfs entries.

To see the list of governers (the output of this command depends on the governors chosen at kernel configuration step):

target$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors
ondemand userspace performance
target$ 

To see the governor being used currently:

target$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
userspace
target$ 

To change governor at runtime:

target$ echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
target$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
performance
target$

Frequency and Voltage scaling

When using the 'ondemand' governor, the kernel takes care of frequency transitions based on processor load. When using 'userspace' governor, the frequency transitions can be initiated from command line. For example:

To set the frequency to 96 MHz

target$ echo 96000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed

NOTE
When using cpufreq only peripherals on a clock domain asynchronous with PLL0 will function correctly. The drivers in this release are not updated to take care of clock input changes. ASYNC3 domain has been configured to derive from PLL1, so is immune to CPU frequency changes.

To see the PLL0 frequency changes occurring because of frequency transitions:

target$ cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

To see the CVDD voltage changes occurring because of CPU load:

target$ cat /sys/class/regulator/regulator.2/microvolts
1150000
target$

CPUIdle

The cpuidle driver in Linux kernel allows CPU to idle efficiently by moving to a state with lower power consumption during idle. Once built in cpuidle driver works automatically and does not require any user intervention.

OMAP-L138 cpuidle driver implements two states

target$ ls /sys/devices/system/cpu/cpu0/cpuidle
state0  state1
target$ 

cpuidle state0 keeps ARM in WFI mode. state1 in addition puts the DDR2/mDDR in power-down mode. Details regarding DDR2/mDDR power down mode are documented in DDR2/mDDR Memory Controller User's Guide section 2.10.

target$ cat /sys/devices/system/cpu/cpu0/cpuidle/state0/desc
Wait for interrupt
target$ cat /sys/devices/system/cpu/cpu0/cpuidle/state1/desc
WFI and DDR Self Refresh
target$

To find usage of state0 and state1 so far since boot-up:

target$ cat /sys/devices/system/cpu/cpu0/cpuidle/state0/usage
6736
target$ cat /sys/devices/system/cpu/cpu0/cpuidle/state1/usage
92724
target$

Suspend-to-RAM

Suspend-to-RAM allows the system to save power by freezing all tasks, asking all drivers to move the devices to a low power state (by disabling the peripheral clock using its LPSC), cutting the clock to external RAM and finally moving the SoC to DeepSleep mode. This user-initiated transtition saves the maximum power among all the power saving mechanisms available.

To put the system into Suspend-to-RAM state use rtcwake command.

rtcwake -d /dev/rtc0 -s 20 -m mem

In the above example, the system remains in suspended state for 20 seconds before coming back up.

IMPORTANT
If you are using MMC/SD card in your system, before suspending the system the MMC/SD card has to be unmounted. If the system is suspended without unmounting the card, the behaviour is undefined, the system may hang and not resume at all. This is a known behaviour for MMC/SD cards in Linux kernel.

Video Port Interface (VPIF)

The Video port interface (VPIF) driver supports NTSC and PAL standards for both display and capture. Currently the driver supports Composite and S-video capture and display.

The bootargs to be set for NTSC display and capture are

u-boot> setenv bootargs console=ttyS2,115200n8 noinitrd rw ip=<ipaddr> root=/dev/nfs nfsroot=<nfs path> ,nolock
mem=32M@0xc0000000 mem=64M@0xc4000000 vpif_capture.ch0_bufsize=692224 vpif_display.ch2_bufsize=692224

The bootargs to be set for PAL display and capture are

u-boot> setenv bootargs console=ttyS2,115200n8 noinitrd rw ip=<ipaddr> root=/dev/nfs nfsroot=<nfs path> ,nolock
mem=32M@0xc0000000 mem=64M@0xc4000000 vpif_capture.ch0_bufsize=831488 vpif_display.ch2_bufsize=831488

NOTE
The entire bootargs has to be entered in a single line.

Example test applications for standalone display and capture-display loopback are included in PSP package under src/examples/vpif. Please refer to the included README file for usage instructions.

The Writing V4L2 Media Controller Applications on Dm36x Video Capture is an introduction to Media Controller and tutorial for writing applications for Video Capture.
The Demonstration of VPIF raw capture using MT9T031 sensor on AM18X/DA850/OMAP-L138 running Linux describes the steps to demonstrate VPIF raw capture using MT9T031 raw bayer sensor on AM18X/DA850/OMAP-L138 running Linux.

Touchscreen

The touchscreen device node is created as /dev/input/touchscreen0. Before using the touchscreen, it needs to be calibrated. Use the command ts_calibrate to do that. To test the touchscreen functionality ts_test can be used.

Note that the SoC does not have a touchscreen controller integrated. The touchscreen functionality is provided by on-board components like TPS65070 or TSC2004.

Timers

Timers in Linux kernel are used to provide clock tick to the kernel and as watchdog timer.

DA830/OMAP-L137/AM17xx

The DA830/OMAP-L137/AM17xx SoCs have two 64-bit timers.

• Timer 0 is configured as two 32-bit timers by kernel at boot-up.
  • Bottom half (12) is used as clockevent and free-run counter.
  • Top half (34) left unused
• Timer 1 will be configured as watchdog timer if support is enabled.

DA850/OMAP-L138/AM18xx

The DA850/OMAP-L138/AM18xx SoCs have four 64-bit timers.

• Timer 0 is configured as two 32-bit timers by kernel at boot-up.
  • Bottom half (12) is used as clockevent.
  • Top half (34) is used as free-run counter.
• Timer 1 will be configured as watchdog timer if support is enabled.
• Timer 2 is left untouched.
• Timer 3 is left untouched.