Updated pages and order

content/documentation/PinePhone/Privacy_switches.adoc

@@ -15,10 +15,7 @@ The PinePhone features six switches that can be used to configure its hardware.
 
 [cols="1,1,1,1"]
 |===
-|Number
-|Name
-|Explanation
-|Description
+| Number | Name | Explanation | Description
 
 | 1
 | Modem

content/documentation/PinePhone_Pro/Various/Replacement_earpieces.adoc → content/documentation/PinePhone_Pro/Hardware/Replacement_earpieces.adoc

@@ -4,8 +4,8 @@ draft: false
 menu:
   docs:
     title:
-    parent: "PinePhone_Pro/Various"
-    identifier: "PinePhone_Pro/Various/Replacement_earpieces"
+    parent: "PinePhone_Pro/Hardware"
+    identifier: "PinePhone_Pro/Hardware/Replacement_earpieces"
     weight: 
 ---
 
@@ -15,6 +15,7 @@ This part is not available to purchase from the PINE64 Store. However, it is pos
 
 Note that the earpiece dimensions for both the PinePhone and PinePhone Pro are 12x6x2 mm. When looking into earpieces not found in this list, aim for these dimensions.
 
+[cols="1,1,1,1"]
 |===
 | Earpiece | PinePhone | PinePhone Pro | Where to Buy
 

content/documentation/PinePhone_Pro/Hardware/_index.adoc

@@ -0,0 +1,12 @@
+---
+title: "Hardware"
+draft: false
+menu:
+  docs:
+    title:
+    parent: "PinePhone_Pro"
+    identifier: "PinePhone_Pro/Hardware"
+    weight: 97
+---
+
+{{< children >}}

content/documentation/PinePhone_Pro/Introduction.adoc

@@ -13,16 +13,12 @@ The PinePhone Pro is PINE64’s second smartphone and a successor to the origina
 
 {{< youtube id="wP2-6Z74W44" >}}
 
-== State of the software
-
-See the page link:/documentation/PinePhone_Pro/Various/Software_state[software state]
-
 == Editions and revisions
 
 Similarly to the original PinePhone, various PinePhone Pro editions are planned, the first of which is the Developer Edition (aimed at developers, as the name entails) followed by the Explorer Edition, which is aimed at early adopters.
 
 * link:/documentation/PinePhone_Pro/Revisions/Developer_Edition[Developer Edition]
-* PinePhone Pro Explorer Edition
+* Explorer Edition
 
 == Help and support
 

content/documentation/PinePhone_Pro/Revisions/Developer_Edition.adoc

@@ -1,6 +1,7 @@
 ---
 title: "Developer Edition"
 draft: false
+hidden: true
 menu:
   docs:
     title:

content/documentation/PinePhone_Pro/Software/Installation_instructions.adoc

@@ -26,7 +26,7 @@ To install an image to the microSD card:
 . Download a compatible image from link:/documentation/PinePhone_Pro/Software/Releases[Releases].
 . *Important:* Typically the image will be compressed in an archive file to reduce the download size (such as _.gz_ or _.xz_). Extract the image from its archive file to get the file with the file extension _.img_.
 . Write the image to your microSD card using your favorite method, examples:
-* Using _dd_: On the device you're flashing the microSD card from, find the correct device under `lsblk` and then flash the image to the microSD card using `sudo dd if=*IMAGE.img* of=/dev/*[DEVICE]* bs=1M status=progress conv=fsync`. Make sure the target is the whole microSD card and not its first partition (_sdc1_ or _mmcblk0p1_ are wrong!).
+* Using _dd_: On the device you're flashing the microSD card from, find the correct device under `lsblk` and then flash the image to the microSD card using `sudo dd if=*IMAGE.img* of=/dev/*[DEVICE]* bs=1M status=progress conv=fsync` and make sure the target is the whole microSD card and not its first partition, _sdc1_ or _mmcblk0p1_ are wrong!
 * Using _bmaptool_: Make sure to select the correct device using `lsblk`. Then run bmaptool with the correct device: Download the _IMAGE.xz_ and the _IMAGE.bmap_ files, then run `bmaptool copy --bmap *IMAGE.bmap* *IMAGE.xz* /dev/*[DEVICE]*`. This takes around 2.5 minutes to flash a 4 GB file.
 * Using _a graphical tool_: A graphical tool such as Gnome Disks under Linux or Etcher under Windows may also be used.
 . Insert the microSD card into the top slot of the PinePhone Pro

content/documentation/PinePhone_Pro/Various/IMX258_camera_debugging → content/documentation/PinePhone_Pro/Various/IMX258_camera_debugging.adoc

@@ -1,6 +1,6 @@
 ---
-title: "PinePhone Pro/IMX258 Camera Debugging"
-draft: false
+title: "IMX258 Camera Debugging"
+draft: false # page seems to break rendering
 menu:
   docs:
     title:
@@ -19,10 +19,10 @@ The Pinephone Pro's rear camera is a Sony IMX258. The camera driver is present u
 
 What do we see in dmesg?
 
-```
+----
 imx258 1-001a: supply vana not found, using dummy regulator
 imx258 1-001a: supply vdig not found, using dummy regulator
-```
+----
 
 This tells us the kernel loads the driver, which is something.
 
@@ -36,7 +36,8 @@ Are these errors bad/fatal? Inspecting the https://github.com/megous/linux/blob/
 
 https://gitlab.com/postmarketOS/megapixels[Megapixels] requires a per-device file to configure cameras. This one isn't complete (most of its numbers are complete nonsense), but it should let us see what happens when Megapixels tries to access the camera:
 `pine64,pinephone-pro.ini`:
-```
+
+----
 [device]
 make=PINE64
 model=PinePhone Pro
@@ -59,14 +60,15 @@ focallength=2.6
 cropfactor=12.7
 fnumber=2.8
 flash-display=true
-```
+----
 
 This segfaulted Megapixels for me. After patching some trivial segfaults, I get fatal GTK4 issues and other tangential problems. Let's try something else.
 
 ==== Manually setting up a camera pipeline
 
 We can roughly follow https://www.kernel.org/doc/html/latest/admin-guide/media/rkisp1.html[this guide]. Doing so gives us the following commands:
-```
+
+----
 "media-ctl" "-d" "platform:rkisp1" "-r"
 "media-ctl" "-d" "platform:rkisp1" "-l" "'imx258 1-001a':0 -> 'rkisp1_isp':0 [1]"
 "media-ctl" "-d" "platform:rkisp1" "-l" "'rkisp1_isp':2 -> 'rkisp1_resizer_selfpath':0 [1]"
@@ -76,10 +78,11 @@ We can roughly follow https://www.kernel.org/doc/html/latest/admin-guide/media/r
 
 "v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "-v" "width=800,height=600,pixelformat=422P"
 "v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "--stream-mmap" "--stream-count" "1" "--verbose"
-```
+----
 
 Careful readers will note that this is setting the camera up with a low resolution compared to what the sensor can do. For some reason I can't get the rkisp1 node to configure its sink pad with the maximum resolution of the sensor (4208x3118). Instead, it sets itself to 4032x3024. This mismatch is forbidden and causes v4l2 to give us EPIPE when we try to enable the stream. Using the lower resolution gets us further--the last command (which attempts to save a single frame of video) gives output like this:
-```
+
+----
 VIDIOC_QUERYCAP: ok
 		VIDIOC_REQBUFS returned 0 (Success)
 		VIDIOC_QUERYBUF returned 0 (Success)
@@ -91,14 +94,15 @@ VIDIOC_QUERYCAP: ok
 		VIDIOC_QBUF returned 0 (Success)
 		VIDIOC_QBUF returned 0 (Success)
 		VIDIOC_STREAMON returned 0 (Success)
-```
+----
 
 But then it just hangs there indefinitely.
 
 Running under strace, we see the program stuck in an ioctl:
-```
+
+----
 ioctl(3, VIDIOC_DQBUF, {type=V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
-```
+----
 
 https://www.kernel.org/doc/html/v4.13/media/uapi/v4l/vidioc-qbuf.html[VIDIOC_DQBUF] corresponds to dequeuing a buffer once it has been filled with an image by the v4l2 device. Apparently, the device never gives us back a captured frame.
 
@@ -117,14 +121,15 @@ Looking back at the driver, it seems we should see errors in dmesg if i2c commun
 We can see if other functions that use i2c produce errors--for example, when we run our `"v4l2-ctl" ... "--stream-mmap"` command, we expect that `imx258_start_streaming` will get called, and this function also writes a load of registers over i2c.
 
 Build and install a kernel with CONFIG_FTRACE (not hard, but outside the scope of this write-up) and enable function graph tracing:
-```
+
+----
 $ sudo su
 . cd /sys/kernel/debug/tracing
 . echo function_graph > current_tracer
 . cat available_filter_functions | grep -E 'rkisp|imx258|v4l2' | awk '{print $1}' > set_graph_function
 . echo 'vm_map_pages,__iommu_map,iommu_map_sg_atomic,rk_iommu_map,__alloc_pages,dma_alloc_attrs,dma_mmap_attrs,__vm_map_pages,vb2_mmap,clk_e,able,schedule_timeout,clk_disable,regmap_write,schedule,__i2c_tra,sfer,i2c_tra,sfer_buffer_flags,dma_free_attrs' | tr , '\n' > set_graph_notrace
 . tee trace_pipe > ~/function-trace.log
-```
+----
 
 Now, in another terminal session, run the `"v4l2-ctl" ... "--stream-mmap"` command again. We end up with a bunch (but hopefully not *too* much) of output in our first terminal and the `~/function-trace.log` file.
 
@@ -135,11 +140,12 @@ A quick grep shows that `imx258_start_streaming` is indeed called, so *i2c is wo
 Our program that asks for a video frame is still hung|We ask the camera to start streaming frames, it presumably does, but the v4l2 stack never tells us a frame has finished. Doing some digging in the v4l2 stack (and the rkisp1 driver), we find out that rkisp1 is notified about frame status via interrupts. We figure this out by manually backtracking through the code to see when `vb2_buffer_done`, the function in the vb2 API to call when a frame is finished, would be called. In the rkisp1 code, `vb2_buffer_done` is only called from `rkisp1_handle_buffer` which is only called from `rkisp1_capture_isr`, which (for the PPP's rk3399 SoC) is only called from `rkisp1_isr`, which is an interrupt handler. We know that it's an interrupt handler from the name (`_isr`), but also because it gets passed (indirectly) to `devm_request_irq` by way of being the `.isr` field of `rk3399_isp_isrs`.
 
 Perhaps the hardware is never actually emitting the interrupt that signals a frame being finished. Indeed, grepping our FTrace log shows that `rkisp1_isr` is never called. A quick look at `/proc/interrupts` shows that *the only interrupt associated with the isp has never triggered* (0 count on every CPU):
-```
+
+----
 . head -n1 /proc/interrupts; grep isp /proc/interrupts
            CPU0       CPU1       CPU2       CPU3       CPU4       CPU5    
  57:          0          0          0          0          0          0     GICv3  75 Level     ff914000.iommu, rkisp1
-```
+----
 
 === `rkisp1` debugfs info
 
@@ -157,16 +163,16 @@ Where do we go from here? I don't know--something may be wrong with the way the
 
 == Megi saves the day
 
-```
+----
 [I] <megi> you might be interested in this https://megous.com/dl/tmp/0ae6ba03a17a3d53.png
 [I] <megi> https://megous.com/git/linux/tag/?h=orange-pi-5.18-20220521-1759
-```
+----
 
 Turns out, the .dts had the wrong ISP connected to the sensor|This is fixed in https://github.com/megous/linux/commit/9afd884f8b36121fb6097e77b6d35fe46ab48ad9[this commit], which is included in kernel version 5.18 or newer.
 
 With a sufficiently new kernel, the following should produce an image (`frame.jpg`):
 
-```
+----
 "media-ctl" "-d" "platform:rkisp1" "-r"
 "media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"imx258 1-001a":0 [fmt:SGRBG10_1X10/1048x780]'
 "media-ctl" "-d" "platform:rkisp1" "-l" "'imx258 1-001a':0 -> 'rkisp1_isp':0 [1]"
@@ -180,11 +186,11 @@ With a sufficiently new kernel, the following should produce an image (`frame.jp
 "v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "--stream-mmap" "--stream-count" "1" "--stream-to=frame.raw"
 
 ffmpeg -y -s:v 1048x780 -pix_fmt yuv422p -i frame.raw frame.jpg
-```
+----
 
 Similarly, you can take a photo from the front camera with the following:
 
-```
+----
 "media-ctl" "-d" "platform:rkisp1" "-r"
 "media-ctl" "-d" "platform:rkisp1" "--set-v4l2" "'m00_f_ov8858 1-0036':0 [fmt:SBGGR10_1X10/1632x1224]"
 "media-ctl" "-d" "platform:rkisp1" "-l" "'m00_f_ov8858 1-0036':0 -> 'rkisp1_isp':0 [1]"
@@ -199,7 +205,7 @@ Similarly, you can take a photo from the front camera with the following:
 "v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "--stream-mmap" "--stream-count" "1" "--stream-to=frame.raw"
 
 ffmpeg -y -s:v 1632x1224 -pix_fmt yuv422p -i frame.raw frame.jpg
-```
+----
 
 In some cases, the isp exposes 2 devices nodes, and the nodes have separate topologies with a different sensor attached to each. In this situation, you may need to reference the isp using the correct device node for the commands to work.
 

content/documentation/PinePhone_Pro/_index.adoc

@@ -4,7 +4,7 @@ draft: false
 menu:
   docs:
     title:
-    parent: ""
+    parent:
     identifier: "PinePhone_Pro"
     weight: 
 ---