Beaglebone Black I/O library 開發歷程(三) - GPIO module

How to access GPIO using mamp in TI AM335x CPU

Base on Beaglebone Black

C Library development note

Author : Cai , Meng-Lun , (VegetableAvenger) , 2013/12/19

Introduction :

這份筆記的內容正式涵蓋了BBBio library的內容，這份文件將介紹如何再Beaglebone black上利用C語言與mmap來進行GPIO的操作，以user space的方式來控制硬體，而不用去撰寫專用的Device Driver，同時粗略的介紹一下AM335x的System Interconnect架構，以瞭解module的布局方式以及Clock manager的管理，最後將演示一段透過BBBio library，使用按鈕開關來控制LED閃爍速度的程式碼。

This note contain :

• AM335x System Interconnect Architecture
•  AM335x GPIO module introduction
•  Memory map of AM335x GPIO module
•  Enable/Disable Clock of GPIO module via CM_PER/CM_WKUP register
•  GPIO register
•  Get BBBio
•  LED Demo

部份文字內容或圖片 reference from : AM335x Technical Reference Manual

AM335x System Interconnect Architecture :

AM335x的interconnect Architecture 為2-Level架構，由L3與L4組成，而L3則分為L3F與L3S，而L4則是分為L4_FAST、L4_PER與L4_WKUP，結構如圖1所示，由其可看出L4_PER與L4_WKUP是掛接在L3_S下，而L4_FAST則是接在L3F下。

圖1、L3 Topology (AM335x TRM page 1231)

而GPIO模組則是分佈在L4之中，GPIO 0掛在L4_WKUP，GPIO 1~3掛在L4_PER中，整體上如圖2所示。

圖2、L4 Topology (AM335x TRM page 1234)

瞭解GPIO模組所屬的Interconnect Topology有助於瞭解各module間的Clock互動情形，即瞭解module所屬的Clock Domain，像是GPIO 1~3所處的Clock Domain為PD_PER_L4LS_GCLK，而GPIO 0 則處在PD_WKUP_L4_WKUP_GCLK這個Clock domain上，而透過圖2的L4 Topology布局方式便可以清楚的瞭解為何GPIO模組會處於不同的Clock Domain上。

為了要讓module省電，所以沒有必要使用的module其Clock常處於Disable的狀態，而每一個GPIO模組擁有其各自的register來控制是否Disable Clock，瞭解其Clock domain之後，便可以搜尋其對應的Clock control register，接著才可以在需要使用時，將GPIO的Clock Enable/Disable，下表為各GPIO的Clock control register：

GPIO	Clock Domain	Speed	Clock Control Register
GPIO 0	PD_WKUP_L4_WKUP_GCLK	100M Hz	CM_WKUP_GPIO0_CLKCTRL
GPIO 1	PD_PER_L4LS_GCLK	100M Hz	CM_PER_GPIO1_CLKCTRL
GPIO 2	PD_PER_L4LS_GCLK	100M Hz	CM_PER_GPIO2_CLKCTRL
GPIO 3	PD_PER_L4LS_GCLK	100M Hz	CM_PER_GPIO3_CLKCTRL

表1、GPIO Clock Domain

AM335x GPIO Module Introduction :

AM335x 擁有4組GPIO module，GPIO 0、GPIO 1、GPIO 2與GPIO 3，每一個module有32支接腳，故總共有128支GPIO的腳位可以使用，每支腳位提供以下的基本功能：

1. Data Input/ Output
2. Debounce cell
3. Synchronous interrupt
4. Wake-up request (Only GPIO 0)

本筆記主要記錄最基本的Data Input/Output，Debouncing為次章節介紹，而剩餘功能尚未完整測試。

基本上每一組GPIO都提供了1~3的基本功能，而GPIO 0 則額外提供了Wake-Pp的功能，是與其他GPIO較為不同的地方，如圖3所示，可以發現GPIO 0的模組配置較GPIO 1~3不同，而圖中各GPIO module的PIDBCLK則為Debouncing Clock的輸入訊號，而POINTRPEND1 /2則是用來產生interrupt的訊號。

 

圖3、GPIO0~3 Module Integeration (AM335x TRM page 4630)

由圖3可知，GPIO模組操作起來所需要的條件並沒有很多，若是不考慮wake up功能的話，基本上GPIO 0~3功能是一樣的，只需要注意在L4 WakeUP Interconnect和L4 Peripgeral Interconnect的Clock有輸入進GPIO模組，接著只要在GPIO module相對應的register之中進行操作，即可控制pin腳的狀態。

Memory map of AM335x GPIO module

接著從AM335x之中，查出GPIO對應的Memory Map的位址，以利用mmap進行存取動作

AM335x TRM，page .171，Table 2-2. L4_WKUP Peripheral Memory Map。

AM335x TRM，page .173~174，Table 2-3. L4_PER Peripheral Memory Map。

Region Name	Start Address	End Address	Size	Description
CM_PER	0x44E0_0000	0x44E0_3FFF	0x4000	Clock Module Peripheral Registers
CM_WKUP	0x44E0_0400	0x44E0_04FF	0x100	Clock Module Wakeup Registers
GPIO0	0x44E0_7000	0x44E0_7FFF	0x1000	GPIO register
GPIO1	0x4804_C000	0x4804_CFFF	0x1000
GPIO2	0x481A_C000	0x481A_CFFFF	0x1000
GPIO3	0x481A_E000	0x481A_EFFFF	0x1000

表2、GPIO Memory map

 

Enable/Disable Clock of GPIO module via CM_PER/CM_WKUP register

在Clock上要特別注意，由先前提過的表1可知，GPIO 0 屬於PD_WKUP_L4_WKUP_GCLK的Clock domain，控制Register為CM_WKUP_GPIO0_CLKCTRL，而GPIO 1~3屬於PD_PER_L4LS_GCLK的Clock domain，控制Register為CM_PER_GPIOx_CLKCTRL (x為1~3)，要小心不要控制錯了，名字是有差別的。

而GPIO模組基本上會有2組Clock的輸入：Interface Clock與Debouncing Clock，Interface Clock由L4 Iterface提供，100MHz的頻率，而Debouncing Clock則是可選的(不需要就Disable沒關係)，為32.768KHz，如果interface clock 沒有Enable，那整組GPIO的register access 都會error，並回傳”Bus Error”的選項。

瞭解要控制的Register之後，接著就是去看他的格式，相對應的頁數列於表3，而基本上這4個reigister的控制參數格式是一模一樣的，如圖4所示，因此我們只需要將Bit 0~1的MODULEMODE欄位設為0x2 (Enable)即可打開相對應GPIO的Clock。

Register Name	Page	Session
CM_WKUP_GPIO0_CLKCTRL	983	Session 8.1.12.2.3
CM_PER_GPIO1_CLKCTRL	947	Session 8.1.12.1.29
CM_PER_GPIO2_CLKCTRL	948	Session 8.1.12.1.30
CM_PER_GPIO3_CLKCTRL	949	Session 8.1.12.1.31

表3、GPIO Clock Register page Reference

 

而這裡有一個需要注意的欄位，OPTFCLKEN_GPIO_x_GDBCLK (bit 18)，這個欄位是用來Enable/Disable Debouncing Clock的，即圖3的PIDBCLK。

圖4、GPIO Clock Register format

 

mmap程式碼：

於BBBio/BBBio.c，iolib_init fnuction之中，需要map 2+4個map，分別是控制Clokc的：CM_PER與CM_WKUP，和GPIO module的GPIO0~3。

其中需要特別注意CM_WKUP，其memory map位址為0x44E0_0400，這個位址直接下去mmap，會回傳error，同時error code為：EINVAL，這是因為0x44E0_0400這個address並沒有alignment page，這裡的page為4K，所以mmap沒有辦法map；不過這是可以處理的，在BBBio中，先mmap CM_PER (0x44E0_0000)這個register，在透過offset 0x400，存取CM_WKUP，即可mmap CM_WKUP，因為在mmap CM_PER時，其map的length已經涵蓋了CM_WKUP。

cm_per_addr = mmap(忽略参數) ; cm_wkup_addr =(void *)cm_per_addr + 0x400 ;

Enable/Disable程式碼：

於BBBio/BBBio.c，BBBIO_sys_Enable_GPIO與BBBIO_sys_Disable_GPIO fnuction之中，

 

GPIO register

GPIO module基本上需要：Input、Output、I/Ｏ方向設定，3個功能，而AM335x的GPIO module則是將這些功能透過以下register控制

Action	Register Name	Offset
I/O Setting	GPIO_OE	0x134
Input	GPIO_DATAIN	0x138
Output	GPIO_CLEARDATAOUT GPIO_SETDATAOUT GPIO_DATAOUT	0x190 0x194 0x13C

表4、GPIO Control Register

I/O Setting：

透過GPIO_OE register來控制PIN腳是要Inpout還是Output，一次設定整組的GPIO I/O status，共32bit，每一個bit對應1個腳位，bit設為0代表output，設為1代表Input。

例如：GPIO 0的GPIO_OE register bit 0代表 GPIO 0 [0]這支pin腳，若是寫入0x00000001，代表將pin0腳位設為input，其他設為output。

請特別注意：建議透過邏輯運算| (or)，來進行操作，因為有些GPIO不是你可以亂動的，以Beaglebone black來說，其外部接角插槽只有96pin，而且有些pin不是GPIO，代表不是每一個GPIO都有拉出去，若是你亂改到非外拉的腳位狀態，或許會造成系統/裝置錯誤，因此，設定數值前請三思並檢查。

 Input Setting：

透過GPIO_DATAIN來取得PIN腳目前輸入的狀態，一次讀入整組的GPIO input status，共32bit，每一個bit對應1個腳位，例如GPIO 0的GPIO_DATAIN register bit 0代表 GPIO 0 [0]這支pin腳，因此讀出GPIO_DATAIN的數值之後，你需要自己利用邏輯運算& (and)，來判斷需要的腳位狀態。

Output Setting：

Output的設定就比較有趣了，這裡我將他分成2種操作模式：獨立控制和直接控制。

 獨立控制代表一次操作下，只可以控制腳位是輸出0還是1

直接控制代表一次操作下，可以一次控制一整組的GPIO狀態，Pin可為0 也可為1。

模式	Register	解說
獨立控制	GPIO_CLEARDATAOUT GPIO_SETDATAOUT	設定Pin腳輸出0 設定Pin腳輸出1
直接控制	GPIO_DATAOUT	設定GPIO輸出

表5、GPIO Output Control Register

假設你需要將8個LED 同一時間一次點亮，那你可以使用獨立控制或是直接控制，但若是同一時間下，需要點亮4個，滅掉4個LED，那就只能使用直接控制的功能，否則你必須使用2次獨立控制的register，先下GPIO_SETDATAOUT 亮4個，在下GPIO_CLEARDATAOUT指令滅4個。

 獨立控制　寫入方式：

一次寫入代表寫入整組的GPIO Output status，共32bit，每一個bit對應1個腳位；要讓某pin腳設為1則在GPIO_SETDATAOUT相對應的bit上寫入1，要設為0，則在GPIO_CLEARDATAOUT上寫入1，你沒看錯，都是寫入1，因為這2個register分別用來進行Output 0和Output 1，寫入1代表此PIN腳要進行設定，寫入0則沒有任何效果。

 直接控制 寫入方式：

直接控制的寫入方式就很直覺了，一樣一次寫入代表寫入整組的GPIO Output status，共32bit，每一個bit對應1個腳位；要某pin腳設為1則在GPIO_DATAOUT相對應的bit上寫入1，要設為0，則在GPIO_DATAOUT上寫入0，跟一般的用法無異。

請特別注意：以上運算一樣建議透過邏輯運算| (or)，來進行操作，因為有些GPIO不是你可以亂動的，以Beaglebone black來說，其外部接角插槽只有96pin，而且有些pin不是GPIO，代表不是每一個GPIO都有拉出去，若是你亂改到非外拉的腳位狀態，或許會造成系統/裝置錯誤，因此，設定數值前請三思並檢查。

Get BBBio

BBBio為Shabaz開發，Cai,Meng-Lun維護的Beaglebone black I/O library，為一套自由軟體，任何人可以自由更改，沒有授權問題，目前置放於github :

https://github.com/VegetableAvenger/BBBIOlib

 LED Demo

圖5為實際範例圖和電路圖，詳細的程式碼請參閱BBBio library中的Demo/Deno_LED_GPIO/

 

圖5、LED Demo & CircuitLayout