diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.rockchip | 53 | ||||
| -rw-r--r-- | doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt | 236 |
2 files changed, 263 insertions, 26 deletions
diff --git a/doc/README.rockchip b/doc/README.rockchip index 9a2ebca95d..e0572c80b9 100644 --- a/doc/README.rockchip +++ b/doc/README.rockchip @@ -14,7 +14,7 @@ many Rockchip devices [1] [2]. The current mainline support is experimental only and is not useful for anything. It should provide a base on which to build. -So far only support for the RK3288 is provided. +So far only support for the RK3288 and RK3036 is provided. Prerequisites @@ -22,7 +22,7 @@ Prerequisites You will need: - - Firefly RK3288 baord + - Firefly RK3288 board or something else with a supported RockChip SoC - Power connection to 5V using the supplied micro-USB power cable - Separate USB serial cable attached to your computer and the Firefly (connect to the micro-USB connector below the logo) @@ -39,12 +39,13 @@ Building At present three RK3288 boards are supported: - Firefly RK3288 - use firefly-rk3288 configuration - - Radxa Rock 2 - also uses firefly-rk3288 configuration - - Haier Chromebook - use chromebook_jerry configuration + - Radxa Rock 2 - use rock2 configuration + - Hisense Chromebook - use chromebook_jerry configuration -one RK3036 board is support: +Two RK3036 board are supported: - - EVB RK3036 - use evb-rk3036_defconfig configuration + - EVB RK3036 - use evb-rk3036 configuration + - Kylin - use kylin_rk3036 configuration For example: @@ -52,11 +53,6 @@ For example: (or you can use another cross compiler if you prefer) -Note that the Radxa Rock 2 uses the Firefly configuration for now as -device tree files are not yet available for the Rock 2. Clearly the two -have hardware differences, so this approach will break down as more drivers -are added. - Writing to the board with USB ============================= @@ -108,20 +104,23 @@ corresponds with this setting in U-Boot: Put this SD (or micro-SD) card into your board and reset it. You should see something like: - U-Boot SPL 2015.07-rc1-00383-ge345740-dirty (Jun 03 2015 - 11:04:40) - - - U-Boot 2015.07-rc1-00383-ge345740-dirty (Jun 03 2015 - 11:04:40) + U-Boot 2016.01-rc2-00309-ge5bad3b-dirty (Jan 02 2016 - 23:41:59 -0700) + Model: Radxa Rock 2 Square DRAM: 2 GiB - MMC: - Using default environment - - In: serial@ff690000 - Out: serial@ff690000 - Err: serial@ff690000 + MMC: dwmmc@ff0f0000: 0, dwmmc@ff0c0000: 1 + *** Warning - bad CRC, using default environment + + In: serial + Out: vop@ff940000.vidconsole + Err: serial + Net: Net Initialization Skipped + No ethernet found. + Hit any key to stop autoboot: 0 => +If you have an HDMI cable attached you should see a video console. + For evb_rk3036 board: ./evb-rk3036/tools/mkimage -n rk3036 -T rksd -d evb-rk3036/spl/u-boot-spl.bin out && \ cat evb-rk3036/u-boot-dtb.bin >> out && \ @@ -175,13 +174,9 @@ Future work Immediate priorities are: -- GPIO (driver exists but is lightly tested) -- I2C (driver exists but is non-functional) - USB host - USB device -- PMIC and regulators (only ACT8846 is supported at present) -- LCD and HDMI -- Run CPU at full speed +- Run CPU at full speed (code exists but we only see ~60 DMIPS maximum) - Ethernet - NAND flash - Support for other Rockchip parts @@ -243,6 +238,12 @@ SPI flash. See above for instructions on how to write a SPI image. +rkmux.py +-------- + +You can use this script to create #defines for SoC register access. See the +script for usage. + Device tree and driver model ---------------------------- diff --git a/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt b/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt new file mode 100644 index 0000000000..b73c96d24f --- /dev/null +++ b/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt @@ -0,0 +1,236 @@ +== Introduction == + +Hardware modules that control pin multiplexing or configuration parameters +such as pull-up/down, tri-state, drive-strength etc are designated as pin +controllers. Each pin controller must be represented as a node in device tree, +just like any other hardware module. + +Hardware modules whose signals are affected by pin configuration are +designated client devices. Again, each client device must be represented as a +node in device tree, just like any other hardware module. + +For a client device to operate correctly, certain pin controllers must +set up certain specific pin configurations. Some client devices need a +single static pin configuration, e.g. set up during initialization. Others +need to reconfigure pins at run-time, for example to tri-state pins when the +device is inactive. Hence, each client device can define a set of named +states. The number and names of those states is defined by the client device's +own binding. + +The common pinctrl bindings defined in this file provide an infrastructure +for client device device tree nodes to map those state names to the pin +configuration used by those states. + +Note that pin controllers themselves may also be client devices of themselves. +For example, a pin controller may set up its own "active" state when the +driver loads. This would allow representing a board's static pin configuration +in a single place, rather than splitting it across multiple client device +nodes. The decision to do this or not somewhat rests with the author of +individual board device tree files, and any requirements imposed by the +bindings for the individual client devices in use by that board, i.e. whether +they require certain specific named states for dynamic pin configuration. + +== Pinctrl client devices == + +For each client device individually, every pin state is assigned an integer +ID. These numbers start at 0, and are contiguous. For each state ID, a unique +property exists to define the pin configuration. Each state may also be +assigned a name. When names are used, another property exists to map from +those names to the integer IDs. + +Each client device's own binding determines the set of states that must be +defined in its device tree node, and whether to define the set of state +IDs that must be provided, or whether to define the set of state names that +must be provided. + +Required properties: +pinctrl-0: List of phandles, each pointing at a pin configuration + node. These referenced pin configuration nodes must be child + nodes of the pin controller that they configure. Multiple + entries may exist in this list so that multiple pin + controllers may be configured, or so that a state may be built + from multiple nodes for a single pin controller, each + contributing part of the overall configuration. See the next + section of this document for details of the format of these + pin configuration nodes. + + In some cases, it may be useful to define a state, but for it + to be empty. This may be required when a common IP block is + used in an SoC either without a pin controller, or where the + pin controller does not affect the HW module in question. If + the binding for that IP block requires certain pin states to + exist, they must still be defined, but may be left empty. + +Optional properties: +pinctrl-1: List of phandles, each pointing at a pin configuration + node within a pin controller. +... +pinctrl-n: List of phandles, each pointing at a pin configuration + node within a pin controller. +pinctrl-names: The list of names to assign states. List entry 0 defines the + name for integer state ID 0, list entry 1 for state ID 1, and + so on. + +For example: + + /* For a client device requiring named states */ + device { + pinctrl-names = "active", "idle"; + pinctrl-0 = <&state_0_node_a>; + pinctrl-1 = <&state_1_node_a &state_1_node_b>; + }; + + /* For the same device if using state IDs */ + device { + pinctrl-0 = <&state_0_node_a>; + pinctrl-1 = <&state_1_node_a &state_1_node_b>; + }; + + /* + * For an IP block whose binding supports pin configuration, + * but in use on an SoC that doesn't have any pin control hardware + */ + device { + pinctrl-names = "active", "idle"; + pinctrl-0 = <>; + pinctrl-1 = <>; + }; + +== Pin controller devices == + +Pin controller devices should contain the pin configuration nodes that client +devices reference. + +For example: + + pincontroller { + ... /* Standard DT properties for the device itself elided */ + + state_0_node_a { + ... + }; + state_1_node_a { + ... + }; + state_1_node_b { + ... + }; + } + +The contents of each of those pin configuration child nodes is defined +entirely by the binding for the individual pin controller device. There +exists no common standard for this content. + +The pin configuration nodes need not be direct children of the pin controller +device; they may be grandchildren, for example. Whether this is legal, and +whether there is any interaction between the child and intermediate parent +nodes, is again defined entirely by the binding for the individual pin +controller device. + +== Generic pin multiplexing node content == + +pin multiplexing nodes: + +function - the mux function to select +groups - the list of groups to select with this function + (either this or "pins" must be specified) +pins - the list of pins to select with this function (either + this or "groups" must be specified) + +Example: + +state_0_node_a { + uart0 { + function = "uart0"; + groups = "u0rxtx", "u0rtscts"; + }; +}; +state_1_node_a { + spi0 { + function = "spi0"; + groups = "spi0pins"; + }; +}; +state_2_node_a { + function = "i2c0"; + pins = "mfio29", "mfio30"; +}; + +== Generic pin configuration node content == + +Many data items that are represented in a pin configuration node are common +and generic. Pin control bindings should use the properties defined below +where they are applicable; not all of these properties are relevant or useful +for all hardware or binding structures. Each individual binding document +should state which of these generic properties, if any, are used, and the +structure of the DT nodes that contain these properties. + +Supported generic properties are: + +pins - the list of pins that properties in the node + apply to (either this or "group" has to be + specified) +group - the group to apply the properties to, if the driver + supports configuration of whole groups rather than + individual pins (either this or "pins" has to be + specified) +bias-disable - disable any pin bias +bias-high-impedance - high impedance mode ("third-state", "floating") +bias-bus-hold - latch weakly +bias-pull-up - pull up the pin +bias-pull-down - pull down the pin +bias-pull-pin-default - use pin-default pull state +drive-push-pull - drive actively high and low +drive-open-drain - drive with open drain +drive-open-source - drive with open source +drive-strength - sink or source at most X mA +input-enable - enable input on pin (no effect on output) +input-disable - disable input on pin (no effect on output) +input-schmitt-enable - enable schmitt-trigger mode +input-schmitt-disable - disable schmitt-trigger mode +input-debounce - debounce mode with debound time X +power-source - select between different power supplies +low-power-enable - enable low power mode +low-power-disable - disable low power mode +output-low - set the pin to output mode with low level +output-high - set the pin to output mode with high level +slew-rate - set the slew rate + +For example: + +state_0_node_a { + cts_rxd { + pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ + bias-pull-up; + }; +}; +state_1_node_a { + rts_txd { + pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ + output-high; + }; +}; +state_2_node_a { + foo { + group = "foo-group"; + bias-pull-up; + }; +}; + +Some of the generic properties take arguments. For those that do, the +arguments are described below. + +- pins takes a list of pin names or IDs as a required argument. The specific + binding for the hardware defines: + - Whether the entries are integers or strings, and their meaning. + +- bias-pull-up, -down and -pin-default take as optional argument on hardware + supporting it the pull strength in Ohm. bias-disable will disable the pull. + +- drive-strength takes as argument the target strength in mA. + +- input-debounce takes the debounce time in usec as argument + or 0 to disable debouncing + +More in-depth documentation on these parameters can be found in +<include/linux/pinctrl/pinconf-generic.h> |