MT6573 YuSu Jogball Customer Document [1.1 ed.]

Citation preview

LY M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

Yusu Jogball Customer Document

Version: Release date:

1.1 2011-01-266

© 2008 - 2011 MediaTek Inc. This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

FO

Specifications are subject to change without notice.

LY

MTXXXX Chip Name Confidential B

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

Document Revision History

Revision

Date

Author

2010-06-16

MingHsien

1.1

2011-01-26

Wenjun Gao

FO

1.0

MediaTek Confidential

Description Initial Draft

Update customization configuration related with MT6573

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 2 of 14

LY

MTXXXX Chip Name Confidential B

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

Table of Contents

Document Revision History .................................................................................................................. 2 Table of Contents................................................................................................................................... 3 1

Introduction................................................................................................................................... 4 1.1

1.2 1.3 1.4

2

Design............................................................................................................................................ 7 2.1 2.2

3

Data Structure....................................................................................................................... 9 Kernel API Of Input Device................................................................................................... 9 3.2.1 input_allocate_device........................................................................................... 9 3.2.2 input_free_device ................................................................................................. 9 3.2.3 input_set_capability.............................................................................................. 9 3.2.4 input_register_device ......................................................................................... 10 3.2.5 input_unregister_device ..................................................................................... 10

Customization............................................................................................................................. 11 4.1 4.2

5

Architecture........................................................................................................................... 7 Procedure & Flow ................................................................................................................. 7

Interface......................................................................................................................................... 9 3.1 3.2

4

Software/Hardware Environment.......................................................................................... 4 1.1.1 Software Environment .......................................................................................... 4 1.1.2 Hardware Environment......................................................................................... 4 Functionality.......................................................................................................................... 4 Hardware background .......................................................................................................... 4 Hardware Component used in this driver ............................................................................. 4

gain_x, gain_y..................................................................................................................... 11 DCT Integration .................................................................................................................. 12

Build............................................................................................................................................. 13

FO

5.1 5.2

Source Code Structure & File Description.......................................................................... 13 Build Option ........................................................................................................................ 13

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 3 of 14

LY

MTXXXX Chip Name Confidential B

Introduction

1.1

Software/Hardware Environment

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

1

1.1.1

Platform

Software Environment

Hardware Environment

MT6516

Linux Kernel 2.6.29 and Android 2.1

MT6516

MT6573

Linux Kernel 2.6.35 and Android 2.3

MT6573

Software Environment

For MT6516 Platform: Driver discussed in this document is designed based on Linux Kernel 2.6.29 and Android 2.1. For MT6573 Platform: Driver discussed in this document is designed based on Linux Kernel 2.6.35 and Android 2.3.

1.1.2

Hardware Environment

Driver discussed in this document can run on the devices with MT6516 or MT6573.

1.2

Functionality

The jogball acts as an input device. It could be used as either keyboard or trackball. For keyboard class, it will report four direction key codes to upper layer. For trackball class, it will report delta movement in x and y axes.

1.3

Hardware background

A jogball is a pointing device consisting of a ball held by a socket containing sensors to detect rotation of the ball in four axes: up / down / right / left.

1.4

Hardware Component used in this driver

FO

The jogball device is manufactured by Panasonic. The top view of the jogball device is as follows:

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 4 of 14

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

LY

MTXXXX Chip Name Confidential B

The major components are four hall sensors, please see the follow picture:

FO

When user pushes the jogball, the waveform of the corresponding pin will be similar to the following picture:

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 5 of 14

LY

MTXXXX Chip Name Confidential B

FO

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

The sensitivity of the jogball devices is 11 pulses / 360 degree. That means the corresponding pins will change between 0 and 1 when user pushes the jogball in that direction. In our EVB, we will connect those pins (up, down, left and right) to the GPIOs which supports external interrupt functionality. Hence, the push of jogball will trigger interrupt because of the change between 0 and 1. Software will trigger key event according to the interrupts.

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 6 of 14

Design

2.1

Architecture

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

2

LY

MTXXXX Chip Name Confidential B

Android designed a simple framework for accessing input devices, such as keypad, mouse, touch panel. The behavior of jogball device in Android is similar to a keyboard device. However, the behavior is simulated by Android Framework. Actually, jogball device driver should be implemented as a trackball class. Android Framework will check trackball device in EventHub if the following conditions are satisfied: (1) The input device registers the key event: BTN_MOUSE (2) The input device registers relative control: REL_X & REL_Y.

2.2

Procedure & Flow

FO

The flow is described as follows: (1) WindowManager will create an instance of KeyInputQueue. When the instance is created, a thread inside the instance will continuously get input event from EventHub. (2) During the first call of getEvent, all the input devices under /dev/input will be opened and checked. According to frameworks\base\include\ui\EventHub.h, six devices are detected: keyboard, alpha MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 7 of 14

LY

MTXXXX Chip Name Confidential B

FO

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

key, touch screen, trackball, multi-touch, DPAD. The handle of detected device will be opened and use poll function call to wait the input event. (3) Once the input event is reported from the polled file handle, the getEvent function will handle those events. (4) The events handled by getEvent will be return to WindowManagerService. The instance of WindowManagerService will dispatch the key event to applications.

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 8 of 14

Interface

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

3

LY

MTXXXX Chip Name Confidential B

Since the interface between Linux kernel and Android platform is input device. Several interface of input device will be briefly introduced in the chapter.

3.1

Data Structure

The most important structure of kernel\include\linux\input.h for detail.

3.2

input

device

is

struct

input_dev.

Please

see

Kernel API Of Input Device

3.2.1

input_allocate_device

Allocate input device Prototype

struct input_dev *input_allocate_device(void) Return Value

The pointer of allocated input device. NULL is returned if no memory.

3.2.2

input_free_device

Free memory occupied by input_dev structure Prototype

void input_free_device(struct input_dev *dev) Parameters In

dev

input device to free

Return Value NONE

3.2.3

input_set_capability

Mark device as capable of a certain event Prototype

void input_set_capability(struct input_dev *dev, unsigned int type, unsigned int code) Parameters In

dev

device that is capable of emitting or accepting event

In

type

type of the event (EV_KEY, EV_REL, etc...)

In

code

event code

Return Value

FO

None

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 9 of 14

input_register_device

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

3.2.4

LY

MTXXXX Chip Name Confidential B

Register device with input core Prototype

int input_register_device(struct input_dev *dev) Parameters In

dev

input device to free

Return Value

0: successful Otherwise: error code

3.2.5

input_unregister_device

Unregister previously registered device Prototype

void input_unregister_device(struct input_dev *dev) Parameters In

dev

input device to free

Return Value

FO

NONE

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 10 of 14

Customization

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

4

LY

MTXXXX Chip Name Confidential B

The corresponding structure is defined in For MT6516 Platform: mtk\src\custom\common\kernel\jogball\inc\cust_jogball.h: For MT6573 Platform: mediatek\custom\common\kernel\jogball\inc\cust_jogball.h:

/*----------------------------------------------------------------------------*/ typedef enum { JBD_DETECT_POLL = 0, JBD_DETECT_EINT = 1, } JBD_DETECT; /*----------------------------------------------------------------------------*/ typedef enum { JBD_CLASS_KEYBOARD, JBD_CLASS_TRACKBALL, } JBD_CLASS; /*----------------------------------------------------------------------------*/ struct jogball_hw { int report_cls; /*refer to JBD_CLASS*/ /*trackball class*/ int gain_x; int gain_y; /*keyboard class*/ int detect; int delay; int gpt_num; int gpt_period; int int int int

acc_cnt; inact_cnt; act_cnt; step;

}; /*----------------------------------------------------------------------------*/

Since the reported class is always defined as JBD_CLASS_TRACKBALL, only gain_x and gain_y will be used for customization. Hence, the customization item in keyboard class will be ignored in the document.

4.1

gain_x, gain_y

FO

They are the gain of x-axis and y-axis when detecting one movement. “One movement” is detected when one of four external interrupt detect the change between 1 and 0. The value is generally set as 1.

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 11 of 14

DCT Integration

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

4.2

LY

MTXXXX Chip Name Confidential B

Since jogball needs four external interrupt in each direction, the four external interrupt pin could be configured using DCT. Please see the following definition generated by DCT: DCT definition

Description

GPIO_JBD_INPUT_UP_PIN GPIO_JBD_INPUT_LEFT_PIN GPIO_JBD_INPUT_RIGHT_PIN GPIO_JBD_INPUT_DOWN_PIN CUST_EINT_HALL_1_NUM CUST_EINT_HALL_1_DEBOUNCE_CN

The GPIO pin corresponding to up EINT. The GPIO pin corresponding to left EINT. The GPIO pin corresponding to right EINT The GPIO pin corresponding to down EINT The ID of up EINT

CUST_EINT_HALL_1_POLARITY

CUST_EINT_HALL_1_SENSITIVE

CUST_EINT_HALL_1_DEBOUNCE_EN

CUST_EINT_HALL_2_NUM CUST_EINT_HALL_2_DEBOUNCE_CN CUST_EINT_HALL_2_POLARITY

CUST_EINT_HALL_2_SENSITIVE

CUST_EINT_HALL_2_DEBOUNCE_EN

CUST_EINT_HALL_3_NUM CUST_EINT_HALL_3_DEBOUNCE_CN CUST_EINT_HALL_3_POLARITY

CUST_EINT_HALL_3_SENSITIVE

CUST_EINT_HALL_3_DEBOUNCE_EN

CUST_EINT_HALL_4_NUM CUST_EINT_HALL_4_DEBOUNCE_CN CUST_EINT_HALL_4_POLARITY

CUST_EINT_HALL_4_SENSITIVE

FO

CUST_EINT_HALL_4_DEBOUNCE_EN

MediaTek Confidential

The debounce count, it will generally set as 0x01 The polarity of external pin. It will be set as low level initially. Since any change between 0 and 1 means movement in jogball device, the polarity will be changed during runtime. The sensitivity external pin. It will generally set as edge sensitive to detect the change between 0 and 1 Enable or Disable debounce. It will generally set as enable (1) The ID of left EINT

The debounce count, it will generally set as 0x01 The polarity of external pin. It will be set as low level initially. Since any change between 0 and 1 means movement in jogball device, the polarity will be changed during runtime. The sensitivity external pin. It will generally set as edge sensitive to detect the change between 0 and 1 Enable or Disable debounce. It will generally set as enable (1) The ID of right EINT

The debounce count, it will generally set as 0x01 The polarity of external pin. It will be set as low level initially. Since any change between 0 and 1 means movement in jogball device, the polarity will be changed during runtime. The sensitivity external pin. It will generally set as edge sensitive to detect the change between 0 and 1 Enable or Disable debounce. It will generally set as enable (1) The ID of down EINT

The debounce count, it will generally set as 0x01 The polarity of external pin. It will be set as low level initially. Since any change between 0 and 1 means movement in jogball device, the polarity will be changed during runtime. The sensitivity external pin. It will generally set as edge sensitive to detect the change between 0 and 1 Enable or Disable debounce. It will generally set as enable (1)

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 12 of 14

LY

MTXXXX Chip Name Confidential B

Build

5.1

Source Code Structure & File Description

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

5

Describe your source code structure along with its file description as follows: For MT6516 Platform: File

Description

alps/kernel/drivers/input/mouse/ evqwjn.c

The driver of jogball device

alps/mtk/src/custom/common/kernel/jogball/inc cust_jogball.h

The header file of jogball customization

alps/mtk/src/custom//kernel/jogball// cust_jogball.c

The content of jogball customization

For MT6573 Platform: File

Description

alps/mediatek/platform//kernel/drivers/mouse/ evqwjn.c

The driver of jogball device

alps/mediate/custom/common/kernel/jogball/inc/ cust_jogball.h

The header file of jogball customization

alps/mediatek/custom//kernel/jogball// cust_jogball.c

5.2

The content of jogball customization

Build Option

FO

For MT6516 Platform: The kernel configuration of jogball is CONFIG_INPUT_MT6516_JOGBALL. User could turn on/off the option by “make menuconfig”: (1) Enter Device Drivers > Misc devices. (2) Enable Jogball driver by pressing space until:

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 13 of 14

M R ED yu IA .li@ T E tin K C no O mo NF bil ID e.c EN om T I US AL EO N

LY

MTXXXX Chip Name Confidential B

(3) Disable Jogball driver by pressing space until:

(4) Please remember to commit the change to board specific kernel configuration file.

FO

For MT6573 Platform: Enable Jogball: 1. Check the configuration file (usually mediatek/config//autoconfig/kconfig/project) 2. Search for CONFIG_INPUT_MOUSE. 3. Set it as “CONFIG_INPUT_MOUSE=y”. 4. Search for CONFIG_MOUSE_PANASONIC_EVQWJN. 5. Set it as “CONFIG_MOUSE_PANASONIC_EVQWJN=y”. 6. Check the ProjectConfig.mk under /mediatek/config//. 7. Search for CUSTOM_KERNEL_JOGBALL. 8. Set it as “CUSTOM_KERNEL_JOGBALL = xxx”. (xxx is the specific module name) Disable Jogball: 1. Check the configuration file (usually mediatek/config//autoconfig/kconfig/project) 2. Search for CONFIG_MOUSE_PANASONIC_EVQWJN. 3. Set it as “CONFIG_MOUSE_PANASONIC_EVQWJN is not set”.

MediaTek Confidential

© 2010 - 2011 MediaTek Inc.

This document contains information that is proprietary to MediaTek Inc. Unauthorized reproduction or disclosure of this information in whole or in part is strictly prohibited.

Page 14 of 14