From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 18:03:13 +0000 (-0300) Subject: docs: add a memory-devices subdir to driver-api X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=652a49bc68ce3cf0355bde357b3998bd63e73915;p=linux.git docs: add a memory-devices subdir to driver-api There are two docs describing memory device drivers. Add both to this new chapter of the driver-api. Signed-off-by: Mauro Carvalho Chehab --- diff --git a/Documentation/bus-devices/ti-gpmc.rst b/Documentation/bus-devices/ti-gpmc.rst deleted file mode 100644 index 87c366e418be7..0000000000000 --- a/Documentation/bus-devices/ti-gpmc.rst +++ /dev/null @@ -1,179 +0,0 @@ -:orphan: - -======================================== -GPMC (General Purpose Memory Controller) -======================================== - -GPMC is an unified memory controller dedicated to interfacing external -memory devices like - - * Asynchronous SRAM like memories and application specific integrated - circuit devices. - * Asynchronous, synchronous, and page mode burst NOR flash devices - NAND flash - * Pseudo-SRAM devices - -GPMC is found on Texas Instruments SoC's (OMAP based) -IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 - - -GPMC generic timing calculation: -================================ - -GPMC has certain timings that has to be programmed for proper -functioning of the peripheral, while peripheral has another set of -timings. To have peripheral work with gpmc, peripheral timings has to -be translated to the form gpmc can understand. The way it has to be -translated depends on the connected peripheral. Also there is a -dependency for certain gpmc timings on gpmc clock frequency. Hence a -generic timing routine was developed to achieve above requirements. - -Generic routine provides a generic method to calculate gpmc timings -from gpmc peripheral timings. struct gpmc_device_timings fields has to -be updated with timings from the datasheet of the peripheral that is -connected to gpmc. A few of the peripheral timings can be fed either -in time or in cycles, provision to handle this scenario has been -provided (refer struct gpmc_device_timings definition). It may so -happen that timing as specified by peripheral datasheet is not present -in timing structure, in this scenario, try to correlate peripheral -timing to the one available. If that doesn't work, try to add a new -field as required by peripheral, educate generic timing routine to -handle it, make sure that it does not break any of the existing. -Then there may be cases where peripheral datasheet doesn't mention -certain fields of struct gpmc_device_timings, zero those entries. - -Generic timing routine has been verified to work properly on -multiple onenand's and tusb6010 peripherals. - -A word of caution: generic timing routine has been developed based -on understanding of gpmc timings, peripheral timings, available -custom timing routines, a kind of reverse engineering without -most of the datasheets & hardware (to be exact none of those supported -in mainline having custom timing routine) and by simulation. - -gpmc timing dependency on peripheral timings: - -[: , ...] - -1. common - -cs_on: - t_ceasu -adv_on: - t_avdasu, t_ceavd - -2. sync common - -sync_clk: - clk -page_burst_access: - t_bacc -clk_activation: - t_ces, t_avds - -3. read async muxed - -adv_rd_off: - t_avdp_r -oe_on: - t_oeasu, t_aavdh -access: - t_iaa, t_oe, t_ce, t_aa -rd_cycle: - t_rd_cycle, t_cez_r, t_oez - -4. read async non-muxed - -adv_rd_off: - t_avdp_r -oe_on: - t_oeasu -access: - t_iaa, t_oe, t_ce, t_aa -rd_cycle: - t_rd_cycle, t_cez_r, t_oez - -5. read sync muxed - -adv_rd_off: - t_avdp_r, t_avdh -oe_on: - t_oeasu, t_ach, cyc_aavdh_oe -access: - t_iaa, cyc_iaa, cyc_oe -rd_cycle: - t_cez_r, t_oez, t_ce_rdyz - -6. read sync non-muxed - -adv_rd_off: - t_avdp_r -oe_on: - t_oeasu -access: - t_iaa, cyc_iaa, cyc_oe -rd_cycle: - t_cez_r, t_oez, t_ce_rdyz - -7. write async muxed - -adv_wr_off: - t_avdp_w -we_on, wr_data_mux_bus: - t_weasu, t_aavdh, cyc_aavhd_we -we_off: - t_wpl -cs_wr_off: - t_wph -wr_cycle: - t_cez_w, t_wr_cycle - -8. write async non-muxed - -adv_wr_off: - t_avdp_w -we_on, wr_data_mux_bus: - t_weasu -we_off: - t_wpl -cs_wr_off: - t_wph -wr_cycle: - t_cez_w, t_wr_cycle - -9. write sync muxed - -adv_wr_off: - t_avdp_w, t_avdh -we_on, wr_data_mux_bus: - t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we -we_off: - t_wpl, cyc_wpl -cs_wr_off: - t_wph -wr_cycle: - t_cez_w, t_ce_rdyz - -10. write sync non-muxed - -adv_wr_off: - t_avdp_w -we_on, wr_data_mux_bus: - t_weasu, t_rdyo -we_off: - t_wpl, cyc_wpl -cs_wr_off: - t_wph -wr_cycle: - t_cez_w, t_ce_rdyz - - -Note: - Many of gpmc timings are dependent on other gpmc timings (a few - gpmc timings purely dependent on other gpmc timings, a reason that - some of the gpmc timings are missing above), and it will result in - indirect dependency of peripheral timings to gpmc timings other than - mentioned above, refer timing routine for more details. To know what - these peripheral timings correspond to, please see explanations in - struct gpmc_device_timings definition. And for gpmc timings refer - IP details (link above). diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index eff22db0ed143..d12a80f386a65 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -79,6 +79,7 @@ available subsections can be seen below. isapnp generic-counter lightnvm-pblk + memory-devices/index men-chameleon-bus ntb nvmem diff --git a/Documentation/driver-api/memory-devices/index.rst b/Documentation/driver-api/memory-devices/index.rst new file mode 100644 index 0000000000000..87549828f6abd --- /dev/null +++ b/Documentation/driver-api/memory-devices/index.rst @@ -0,0 +1,16 @@ +========================= +Memory Controller drivers +========================= + +.. toctree:: + :maxdepth: 1 + + ti-emif + ti-gpmc + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/memory-devices/ti-emif.rst b/Documentation/driver-api/memory-devices/ti-emif.rst new file mode 100644 index 0000000000000..dea2ad9bcd7ec --- /dev/null +++ b/Documentation/driver-api/memory-devices/ti-emif.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +TI EMIF SDRAM Controller Driver +=============================== + +Author +====== +Aneesh V + +Location +======== +driver/memory/emif.c + +Supported SoCs: +=============== +TI OMAP44xx +TI OMAP54xx + +Menuconfig option: +================== +Device Drivers + Memory devices + Texas Instruments EMIF driver + +Description +=========== +This driver is for the EMIF module available in Texas Instruments +SoCs. EMIF is an SDRAM controller that, based on its revision, +supports one or more of DDR2, DDR3, and LPDDR2 SDRAM protocols. +This driver takes care of only LPDDR2 memories presently. The +functions of the driver includes re-configuring AC timing +parameters and other settings during frequency, voltage and +temperature changes + +Platform Data (see include/linux/platform_data/emif_plat.h) +=========================================================== +DDR device details and other board dependent and SoC dependent +information can be passed through platform data (struct emif_platform_data) + +- DDR device details: 'struct ddr_device_info' +- Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck' +- Custom configurations: customizable policy options through + 'struct emif_custom_configs' +- IP revision +- PHY type + +Interface to the external world +=============================== +EMIF driver registers notifiers for voltage and frequency changes +affecting EMIF and takes appropriate actions when these are invoked. + +- freq_pre_notify_handling() +- freq_post_notify_handling() +- volt_notify_handling() + +Debugfs +======= +The driver creates two debugfs entries per device. + +- regcache_dump : dump of register values calculated and saved for all + frequencies used so far. +- mr4 : last polled value of MR4 register in the LPDDR2 device. MR4 + indicates the current temperature level of the device. diff --git a/Documentation/driver-api/memory-devices/ti-gpmc.rst b/Documentation/driver-api/memory-devices/ti-gpmc.rst new file mode 100644 index 0000000000000..33efcb81f0803 --- /dev/null +++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst @@ -0,0 +1,179 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +GPMC (General Purpose Memory Controller) +======================================== + +GPMC is an unified memory controller dedicated to interfacing external +memory devices like + + * Asynchronous SRAM like memories and application specific integrated + circuit devices. + * Asynchronous, synchronous, and page mode burst NOR flash devices + NAND flash + * Pseudo-SRAM devices + +GPMC is found on Texas Instruments SoC's (OMAP based) +IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 + + +GPMC generic timing calculation: +================================ + +GPMC has certain timings that has to be programmed for proper +functioning of the peripheral, while peripheral has another set of +timings. To have peripheral work with gpmc, peripheral timings has to +be translated to the form gpmc can understand. The way it has to be +translated depends on the connected peripheral. Also there is a +dependency for certain gpmc timings on gpmc clock frequency. Hence a +generic timing routine was developed to achieve above requirements. + +Generic routine provides a generic method to calculate gpmc timings +from gpmc peripheral timings. struct gpmc_device_timings fields has to +be updated with timings from the datasheet of the peripheral that is +connected to gpmc. A few of the peripheral timings can be fed either +in time or in cycles, provision to handle this scenario has been +provided (refer struct gpmc_device_timings definition). It may so +happen that timing as specified by peripheral datasheet is not present +in timing structure, in this scenario, try to correlate peripheral +timing to the one available. If that doesn't work, try to add a new +field as required by peripheral, educate generic timing routine to +handle it, make sure that it does not break any of the existing. +Then there may be cases where peripheral datasheet doesn't mention +certain fields of struct gpmc_device_timings, zero those entries. + +Generic timing routine has been verified to work properly on +multiple onenand's and tusb6010 peripherals. + +A word of caution: generic timing routine has been developed based +on understanding of gpmc timings, peripheral timings, available +custom timing routines, a kind of reverse engineering without +most of the datasheets & hardware (to be exact none of those supported +in mainline having custom timing routine) and by simulation. + +gpmc timing dependency on peripheral timings: + +[: , ...] + +1. common + +cs_on: + t_ceasu +adv_on: + t_avdasu, t_ceavd + +2. sync common + +sync_clk: + clk +page_burst_access: + t_bacc +clk_activation: + t_ces, t_avds + +3. read async muxed + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu, t_aavdh +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez + +4. read async non-muxed + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez + +5. read sync muxed + +adv_rd_off: + t_avdp_r, t_avdh +oe_on: + t_oeasu, t_ach, cyc_aavdh_oe +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz + +6. read sync non-muxed + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz + +7. write async muxed + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_aavdh, cyc_aavhd_we +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle + +8. write async non-muxed + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle + +9. write sync muxed + +adv_wr_off: + t_avdp_w, t_avdh +we_on, wr_data_mux_bus: + t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz + +10. write sync non-muxed + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_rdyo +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz + + +Note: + Many of gpmc timings are dependent on other gpmc timings (a few + gpmc timings purely dependent on other gpmc timings, a reason that + some of the gpmc timings are missing above), and it will result in + indirect dependency of peripheral timings to gpmc timings other than + mentioned above, refer timing routine for more details. To know what + these peripheral timings correspond to, please see explanations in + struct gpmc_device_timings definition. And for gpmc timings refer + IP details (link above). diff --git a/Documentation/memory-devices/ti-emif.rst b/Documentation/memory-devices/ti-emif.rst deleted file mode 100644 index c9242294e63c6..0000000000000 --- a/Documentation/memory-devices/ti-emif.rst +++ /dev/null @@ -1,64 +0,0 @@ -:orphan: - -=============================== -TI EMIF SDRAM Controller Driver -=============================== - -Author -====== -Aneesh V - -Location -======== -driver/memory/emif.c - -Supported SoCs: -=============== -TI OMAP44xx -TI OMAP54xx - -Menuconfig option: -================== -Device Drivers - Memory devices - Texas Instruments EMIF driver - -Description -=========== -This driver is for the EMIF module available in Texas Instruments -SoCs. EMIF is an SDRAM controller that, based on its revision, -supports one or more of DDR2, DDR3, and LPDDR2 SDRAM protocols. -This driver takes care of only LPDDR2 memories presently. The -functions of the driver includes re-configuring AC timing -parameters and other settings during frequency, voltage and -temperature changes - -Platform Data (see include/linux/platform_data/emif_plat.h) -=========================================================== -DDR device details and other board dependent and SoC dependent -information can be passed through platform data (struct emif_platform_data) - -- DDR device details: 'struct ddr_device_info' -- Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck' -- Custom configurations: customizable policy options through - 'struct emif_custom_configs' -- IP revision -- PHY type - -Interface to the external world -=============================== -EMIF driver registers notifiers for voltage and frequency changes -affecting EMIF and takes appropriate actions when these are invoked. - -- freq_pre_notify_handling() -- freq_post_notify_handling() -- volt_notify_handling() - -Debugfs -======= -The driver creates two debugfs entries per device. - -- regcache_dump : dump of register values calculated and saved for all - frequencies used so far. -- mr4 : last polled value of MR4 register in the LPDDR2 device. MR4 - indicates the current temperature level of the device.