| Bryan Huntsman | 3f2bc4d | 2011-08-16 17:27:22 -0700 | [diff] [blame] | 1 | Introduction: |
| 2 | ============= |
| 3 | |
| 4 | The msm_rng device driver handles random number generation |
| 5 | using hardware present in MSM chipsets. |
| 6 | |
| 7 | Hardware description: |
| 8 | ===================== |
| 9 | |
| 10 | The supported hardware is a macro block within a system-on-a-chip (SoC). |
| 11 | The hardware is pseudo random number generator (PRNG) with four oscillators |
| 12 | setup with a linear feedback shift register (LFSR). |
| 13 | The hardware must be initially configured once for normal operation and |
| 14 | a 32bit FIFO is read to obtain hardware generated pseudo random numbers. |
| 15 | Currently the driver configures the hardware registers during initialization |
| 16 | and the future plan is to have the boot loader configure these registers and |
| 17 | write lock them so only host OS can read them and the driver writes will be |
| 18 | ignored. |
| 19 | |
| 20 | Software description |
| 21 | ==================== |
| 22 | |
| 23 | The driver is based on the platform_driver model. It registers an entry, |
| 24 | exit and probe functions. Once the probe function is called, the driver |
| 25 | registers a callback function with the hwrng (Hardware Random Number Generator) |
| 26 | subsystem that is called when the hardware device (i.e. /dev/hw_random) is |
| 27 | requesting random data from this device. |
| 28 | Once the callback is issued from the hwrng subsystem, the driver checks to |
| 29 | make sure the hardware has random data available and determines the maximum |
| 30 | data it can return and returns that much data back. |
| 31 | |
| 32 | Power Management |
| 33 | ================ |
| 34 | |
| 35 | Initially, no services are provided in the area of power management. |
| 36 | |
| 37 | SMP/multi-core |
| 38 | ============== |
| 39 | |
| 40 | The locking mechanism for the hwrng operations is taken care of by the hwrng |
| 41 | framework. There are no SMP situations within the driver that need addressing. |
| 42 | |
| 43 | Driver parameters |
| 44 | ================= |
| 45 | |
| 46 | This driver is built and statically linked into the kernel; therefore, |
| 47 | there are no module parameters supported by this driver. |
| 48 | |
| 49 | There are no kernel command line parameters supported by this driver. |
| 50 | |
| 51 | Config options |
| 52 | ============== |
| 53 | |
| 54 | This driver is enabled by the kernel config option CONFIG_HW_RANDOM_MSM. |
| 55 | The option CONFIG_HW_RANDOM_MSM depends on HW_RANDOM && ARCH_MSM. |
| 56 | |
| 57 | Dependencies: |
| 58 | ============= |
| 59 | |
| 60 | This driver depends on the HW_RANDOM subsystem to register with and get |
| 61 | callbacks to request random data. |
| 62 | |
| 63 | User space utilities: |
| 64 | ===================== |
| 65 | |
| 66 | The driver alone does not feed random numbers into kernel but just provides a |
| 67 | method to get random numbers to a known device (i.e. /dev/hw_random). A user- |
| 68 | space utility is required to monitor the /dev/random device entropy pool and |
| 69 | feed it from the /dev/hw_random device. This application also must perform some |
| 70 | sort of sanity checking on the returned data to make sure the data is not all |
| 71 | the same. |
| 72 | |
| 73 | There is currently a GPL v2 tool called rng-tools that has a daemon called, |
| 74 | "rngd" that performs this functionality. There is also a test tool in this |
| 75 | package that tests the whole random subsystem. |