^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) FPGA Manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The FPGA manager core exports a set of functions for programming an FPGA with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) an image. The API is manufacturer agnostic. All manufacturer specifics are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) hidden away in a low level driver which registers a set of ops with the core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The FPGA image data itself is very manufacturer specific, but for our purposes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) it's just binary data. The FPGA manager core won't parse it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) The FPGA image to be programmed can be in a scatter gather list, a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) contiguous buffer, or a firmware file. Because allocating contiguous kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) memory for the buffer should be avoided, users are encouraged to use a scatter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) gather list instead if possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The particulars for programming the image are presented in a structure (struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) fpga_image_info). This struct contains parameters such as pointers to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) FPGA image as well as image-specific particulars such as whether the image was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) built for full or partial reconfiguration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) How to support a new FPGA device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) To add another FPGA manager, write a driver that implements a set of ops. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) probe function calls fpga_mgr_register(), such as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) static const struct fpga_manager_ops socfpga_fpga_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) .write_init = socfpga_fpga_ops_configure_init,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) .write = socfpga_fpga_ops_configure_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) .write_complete = socfpga_fpga_ops_configure_complete,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) .state = socfpga_fpga_ops_state,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) static int socfpga_fpga_probe(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) struct device *dev = &pdev->dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) struct socfpga_fpga_priv *priv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) struct fpga_manager *mgr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) int ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) if (!priv)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) * do ioremaps, get interrupts, etc. and save
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) * them in priv
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) mgr = devm_fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) &socfpga_fpga_ops, priv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) if (!mgr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) platform_set_drvdata(pdev, mgr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) return fpga_mgr_register(mgr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) static int socfpga_fpga_remove(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) struct fpga_manager *mgr = platform_get_drvdata(pdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) fpga_mgr_unregister(mgr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) The ops will implement whatever device specific register writes are needed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) do the programming sequence for this particular FPGA. These ops return 0 for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) success or negative error codes otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The programming sequence is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) 1. .write_init
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) 2. .write or .write_sg (may be called once or multiple times)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) 3. .write_complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) The .write_init function will prepare the FPGA to receive the image data. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) buffer passed into .write_init will be at most .initial_header_size bytes long;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) if the whole bitstream is not immediately available then the core code will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) buffer up at least this much before starting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) The .write function writes a buffer to the FPGA. The buffer may be contain the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) whole FPGA image or may be a smaller chunk of an FPGA image. In the latter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) case, this function is called multiple times for successive chunks. This interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) is suitable for drivers which use PIO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) The .write_sg version behaves the same as .write except the input is a sg_table
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) scatter list. This interface is suitable for drivers which use DMA.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) The .write_complete function is called after all the image has been written
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) to put the FPGA into operating mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) The ops include a .state function which will determine the state the FPGA is in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) and return a code of type enum fpga_mgr_states. It doesn't result in a change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) in state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) API for implementing a new FPGA Manager driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * ``fpga_mgr_states`` — Values for :c:expr:`fpga_manager->state`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) * struct fpga_manager — the FPGA manager struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) * struct fpga_manager_ops — Low level FPGA manager driver ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * devm_fpga_mgr_create() — Allocate and init a manager struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * fpga_mgr_register() — Register an FPGA manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) * fpga_mgr_unregister() — Unregister an FPGA manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) .. kernel-doc:: include/linux/fpga/fpga-mgr.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) :functions: fpga_mgr_states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) .. kernel-doc:: include/linux/fpga/fpga-mgr.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) :functions: fpga_manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) .. kernel-doc:: include/linux/fpga/fpga-mgr.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) :functions: fpga_manager_ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) .. kernel-doc:: drivers/fpga/fpga-mgr.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) :functions: devm_fpga_mgr_create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) .. kernel-doc:: drivers/fpga/fpga-mgr.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) :functions: fpga_mgr_register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) .. kernel-doc:: drivers/fpga/fpga-mgr.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) :functions: fpga_mgr_unregister
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags