1For both Cherrytrail (CHT) and Baytrail (BHT) the driver
2requires the "candrpv_0415_20150521_0458" firmware version.
3It should be noticed that the firmware file is different,
4depending on the ISP model, so they're stored with different
5names:
6
7- for BHT: /lib/firmware/shisp_2400b0_v21.bin
8
9  Warning: The driver was not tested yet for BHT.
10
11- for CHT: /lib/firmware/shisp_2401a0_v21.bin
12
13  https://github.com/intel-aero/meta-intel-aero-base/blob/master/recipes-kernel/linux/linux-yocto/shisp_2401a0_v21.bin
14
15NOTE:
16=====
17
18This driver currently doesn't work with most V4L2 applications,
19as there are still some issues with regards to implementing
20certain APIs at the standard way.
21
22Also, currently only USERPTR streaming mode is working.
23
24In order to test, it is needed to know what's the sensor's
25resolution. This can be checked with:
26
27$ v4l2-ctl --get-fmt-video
28  Format Video Capture:
29	Width/Height      : 1600/1200
30	...
31
32It is known to work with:
33
34- v4l2grab at contrib/test directory at https://git.linuxtv.org/v4l-utils.git/
35
36  The resolution should not be bigger than the max resolution
37  supported by the sensor, or it will fail. So, if the sensor
38  reports:
39
40  The driver can be tested with:
41
42  v4l2grab -f YUYV -x 1600 -y 1200 -d /dev/video2 -u
43
44- NVT at https://github.com/intel/nvt
45
46  $ ./v4l2n -o testimage_@.raw \
47		 --device /dev/video2 \
48		 --input 0 \
49		 --exposure=30000,30000,30000,30000 \
50		 --parm type=1,capturemode=CI_MODE_PREVIEW \
51		 --fmt type=1,width=1600,height=1200,pixelformat=YUYV \
52		 --reqbufs count=2,memory=USERPTR \
53		 --parameters=wb_config.r=32768,wb_config.gr=21043,wb_config.gb=21043,wb_config.b=30863 \
54		 --capture=20
55
56  As the output is in raw format, images need to be converted with:
57
58  $ for i in $(seq 0 19); do
59	name="testimage_$(printf "%03i" $i)"
60	./raw2pnm -x$WIDTH -y$HEIGHT -f$FORMAT $name.raw $name.pnm
61	rm $name.raw
62    done
63
64TODO
65====
66
671.  Fix support for MMAP streaming mode. This is required for most
68    V4L2 applications;
69
702.  Implement and/or fix V4L2 ioctls in order to allow a normal app to
71    use it;
72
733.  Ensure that the driver will pass v4l2-compliance tests;
74
754.  Get manufacturer's authorization to redistribute the binaries for
76    the firmware files;
77
785.  remove VIDEO_ATOMISP_ISP2401, making the driver to auto-detect the
79    register address differences between ISP2400 and ISP2401;
80
816.  Cleanup the driver code, removing the abstraction layers inside it;
82
837.  The atomisp doesn't rely at the usual i2c stuff to discover the
84    sensors. Instead, it calls a function from atomisp_gmin_platform.c.
85    There are some hacks added there for it to wait for sensors to be
86    probed (with a timeout of 2 seconds or so). This should be converted
87    to the usual way, using V4L2 async subdev framework to wait for
88    cameras to be probed;
89
908.  Switch to standard V4L2 sub-device API for sensor and lens. In
91    particular, the user space API needs to support V4L2 controls as
92    defined in the V4L2 spec and references to atomisp must be removed from
93    these drivers.
94
959.  Use LED flash API for flash LED drivers such as LM3554 (which already
96    has a LED class driver).
97
9810. Migrate the sensor drivers out of staging or re-using existing
99    drivers;
100
10111. Switch the driver to use pm_runtime stuff. Right now, it probes the
102    existing PMIC code and sensors call it directly.
103
10412. There's a problem on sensor drivers: when trying to set a video
105    format, the atomisp main driver calls the sensor drivers with the
106    sensor turned off. This causes them to fail.
107
108    This was fixed at atomisp-ov2880, which has a hack inside it
109    to turn it on when VIDIOC_S_FMT is called, but this has to be
110    cheked on other drivers as well.
111
112    The right fix seems to power on the sensor when a video device is
113    opened (or at the first VIDIOC_ ioctl - except for VIDIOC_QUERYCAP),
114    powering it down at close() syscall.
115
116    Such kind of control would need to be done inside the atomisp driver,
117    not at the sensors code.
118
11913. There are several issues related to memory management, that can
120    cause crashes and/or memory leaks. The atomisp splits the memory
121    management on three separate regions:
122
123	- dynamic pool;
124	- reserved pool;
125	- generic pool
126
127    The code implementing it is at:
128
129	drivers/staging/media/atomisp/pci/hmm/
130
131    It also has a separate code for managing DMA buffers at:
132
133	drivers/staging/media/atomisp/pci/mmu/
134
135    The code there is really dirty, ugly and probably wrong. I fixed
136    one bug there already, but the best would be to just trash it and use
137    something else. Maybe the code from the newer intel driver could
138    serve as a model:
139
140	drivers/staging/media/ipu3/ipu3-mmu.c
141
142    But converting it to use something like that is painful and may
143    cause some breakages.
144
14514. The file structure needs to get tidied up to resemble a normal Linux
146    driver.
147
14815. Lots of the midlayer glue. Unused code and abstraction needs removing.
149
15016. The AtomISP driver includes some special IOCTLS (ATOMISP_IOC_XXXX_XXXX)
151    and controls that require some cleanup. Some of those code may have
152    been removed during the cleanups. They could be needed in order to
153    properly support 3A algorithms.
154
155    Such IOCTL interface needs more documentation. The better would
156    be to use something close to the interface used by the IPU3 IMGU driver.
157
15817. The ISP code has some dependencies of the exact FW version.
159    The version defined in pci/sh_css_firmware.c:
160
161    BYT (isp2400): "irci_stable_candrpv_0415_20150521_0458"
162
163    CHT (isp2401): "irci_ecr - master_20150911_0724"
164
165    Those versions don't seem to be available anymore. On the tests we've
166    done so far, this version also seems to work for CHT:
167
168		"irci_stable_candrpv_0415_20150521_0458"
169
170    Which can be obtainable from Yocto Atom ISP respository.
171
172    but this was not thoroughly tested.
173
174    At some point we may need to round up a few driver versions and see if
175    there are any specific things that can be done to fold in support for
176    multiple firmware versions.
177
178
17918. Switch from videobuf1 to videobuf2. Videobuf1 is being removed!
180
18119. Correct Coding Style. Please refrain sending coding style patches
182    for this driver until the other work is done, as there will be a lot
183    of code churn until this driver becomes functional again.
184
18520. Remove the logic which sets up pipelines inside it, moving it to
186    libcamera and implement MC support.
187
188
189Limitations
190===========
191
1921. To test the patches, you also need the ISP firmware
193
194   for BYT: /lib/firmware/shisp_2400b0_v21.bin
195   for CHT: /lib/firmware/shisp_2401a0_v21.bin
196
197   The firmware files will usually be found in /etc/firmware on an Android
198   device but can also be extracted from the upgrade kit if you've managed
199   to lose them somehow.
200
2012. Without a 3A library the capture behaviour is not very good. To take a good
202   picture, you need tune ISP parameters by IOCTL functions or use a 3A library
203   such as libxcam.
204
2053. The driver is intended to drive the PCI exposed versions of the device.
206   It will not detect those devices enumerated via ACPI as a field of the
207   i915 GPU driver.
208
209   There are some patches adding i915 GPU support floating at the Yocto's
210   Aero repository (so far, untested upstream).
211
2124. The driver supports only v2 of the IPU/Camera. It will not work with the
213   versions of the hardware in other SoCs.
214