Supporting Legacy Boards

Legacy board를 software node로 이전

문서 제목은 `Supporting Legacy Boards`입니다. `leds-gpio`, `gpio-keys` 같은 많은 kernel driver가 board별 `platform_data`에서 통합 device-properties interface로 이동하고 있습니다. Driver는 표준 방식으로 property를 조회할 수 있어 더 단순하고 generic해집니다.

Modern system은 이 property를 Device Tree로 제공합니다. 그러나 Device Tree로 전환되지 않은 오래된 platform은 board file에 hardware configuration을 기술합니다. Kernel은 이런 legacy board와 modern generic driver 사이의 간극을 메우기 위해 software node mechanism을 제공합니다.

이 문서는 GPIO-connected device를 기술하던 legacy board file의 `platform_data`와 `gpiod_lookup_table`을 modern software-node 방식으로 변환하는 절차를 설명합니다.

Software node의 핵심 개념

Software node를 사용하면 board-specific code가 `struct software_node`와 `struct property_entry`로 memory 안에 Device-Tree와 비슷한 구조를 만들 수 있습니다.

이 구조를 platform device와 연결하면 driver는 ACPI나 Device Tree system에서처럼 `device_property_read_u32()`, `device_property_read_string()` 같은 standard device-properties API로 configuration을 조회합니다.

Gpiolib은 software node를 처리합니다. 다음 절의 규칙에 맞게 GPIO를 기술하면 `gpiod_get()`, `gpiod_get_optional()` 등 일반 gpiolib API가 그대로 동작합니다.

GPIO property 참조 요구사항

Software node로 GPIO connection을 기술할 때 GPIO core가 reference를 올바르게 해석하려면 세 요구사항을 지켜야 합니다.

• GPIO controller software node의 `name`은 controller의 `label`과 같아야 합니다. Gpiolib core가 runtime에 대응 `struct gpio_chip`을 찾는 key입니다. 이 node는 등록해야 하지만 GPIO controller device에 attach할 필요는 없고 free-floating node여도 됩니다.
• GPIO property는 reference여야 합니다. `PROPERTY_ENTRY_GPIO()`는 `PROPERTY_ENTRY_REF()`의 alias이므로 이 형식을 자동으로 만듭니다.
• Reference argument는 정확히 두 개여야 합니다. 첫째는 controller 내부 GPIO offset, 둘째는 `GPIO_ACTIVE_HIGH`·`GPIO_ACTIVE_LOW` 같은 line flag입니다.

Software node에서 GPIO property를 정의할 때는 `PROPERTY_ENTRY_GPIO()` macro 사용을 권장합니다.

변환 전: platform data와 lookup table

예제는 GPIO에 연결된 LED와 button을 정의하는 board file을 변환합니다. 전형적인 legacy board file은 다음과 같습니다.

.. code-block:: c

  #include <linux/platform_device.h>
  #include <linux/leds.h>
  #include <linux/gpio_keys.h>
  #include <linux/gpio/machine.h>

  #define MYBOARD_GPIO_CONTROLLER "gpio-foo"

  /* LED setup */
  static const struct gpio_led myboard_leds[] = {
          {
                  .name = "myboard:green:status",
                  .default_trigger = "heartbeat",
          },
  };

  static const struct gpio_led_platform_data myboard_leds_pdata = {
          .num_leds = ARRAY_SIZE(myboard_leds),
          .leds = myboard_leds,
  };

  static struct gpiod_lookup_table myboard_leds_gpios = {
          .dev_id = "leds-gpio",
          .table = {
                  GPIO_LOOKUP_IDX(MYBOARD_GPIO_CONTROLLER, 42, NULL, 0, GPIO_ACTIVE_HIGH),
                  { },
          },
  };

  /* Button setup */
  static struct gpio_keys_button myboard_buttons[] = {
          {
                  .code = KEY_WPS_BUTTON,
                  .desc = "WPS Button",
                  .active_low = 1,
          },
  };

  static const struct gpio_keys_platform_data myboard_buttons_pdata = {
          .buttons = myboard_buttons,
          .nbuttons = ARRAY_SIZE(myboard_buttons),
  };

  static struct gpiod_lookup_table myboard_buttons_gpios = {
          .dev_id = "gpio-keys",
          .table = {
                  GPIO_LOOKUP_IDX(MYBOARD_GPIO_CONTROLLER, 15, NULL, 0, GPIO_ACTIVE_LOW),
                  { },
          },
  };

  /* Device registration */
  static int __init myboard_init(void)
  {
          gpiod_add_lookup_table(&myboard_leds_gpios);
          gpiod_add_lookup_table(&myboard_buttons_gpios);

          platform_device_register_data(NULL, "leds-gpio", -1,
                                        &myboard_leds_pdata, sizeof(myboard_leds_pdata));
          platform_device_register_data(NULL, "gpio-keys", -1,
                                        &myboard_buttons_pdata, sizeof(myboard_buttons_pdata));

          return 0;
  }

LED 쪽은 `gpio_led_platform_data`와 `gpiod_lookup_table`을 따로 만들고 controller `gpio-foo`의 offset 42를 `GPIO_ACTIVE_HIGH`로 연결합니다. Button 쪽은 `gpio_keys_platform_data`와 별도 lookup table을 만들고 offset 15를 `GPIO_ACTIVE_LOW`로 연결합니다.

초기화에서는 `gpiod_add_lookup_table()`을 두 번 호출한 뒤 `platform_device_register_data()`로 `leds-gpio`와 `gpio-keys`에 board-specific platform data를 전달합니다.

1단계: GPIO controller node 정의

같은 configuration을 software node로 표현하는 첫 단계는 LED와 button이 연결된 GPIO controller를 나타내는 node를 정의하는 것입니다. Node의 `name`은 GPIO controller driver 이름, 예제에서는 `gpio-foo`와 같아야 합니다.

.. code-block:: c

  #include <linux/property.h>
  #include <linux/gpio/property.h>

  #define MYBOARD_GPIO_CONTROLLER "gpio-foo"

  static const struct software_node myboard_gpio_controller_node = {
          .name = MYBOARD_GPIO_CONTROLLER,
  };

`linux/property.h`와 `linux/gpio/property.h`를 include하고 `myboard_gpio_controller_node`의 name에 `MYBOARD_GPIO_CONTROLLER`를 지정합니다.

2단계: Consumer node와 property 정의

다음으로 LED와 button consumer device의 software node를 정의합니다. Device type별 parent node를 만들고 각 LED 또는 button마다 child node를 둡니다.

.. code-block:: c

  /* LED setup */
  static const struct software_node myboard_leds_node = {
          .name = "myboard-leds",
  };

  static const struct property_entry myboard_status_led_props[] = {
          PROPERTY_ENTRY_STRING("label", "myboard:green:status"),
          PROPERTY_ENTRY_STRING("linux,default-trigger", "heartbeat"),
          PROPERTY_ENTRY_GPIO("gpios", &myboard_gpio_controller_node, 42, GPIO_ACTIVE_HIGH),
          { }
  };

  static const struct software_node myboard_status_led_swnode = {
          .name = "status-led",
          .parent = &myboard_leds_node,
          .properties = myboard_status_led_props,
  };

  /* Button setup */
  static const struct software_node myboard_keys_node = {
          .name = "myboard-keys",
  };

  static const struct property_entry myboard_wps_button_props[] = {
          PROPERTY_ENTRY_STRING("label", "WPS Button"),
          PROPERTY_ENTRY_U32("linux,code", KEY_WPS_BUTTON),
          PROPERTY_ENTRY_GPIO("gpios", &myboard_gpio_controller_node, 15, GPIO_ACTIVE_LOW),
          { }
  };

  static const struct software_node myboard_wps_button_swnode = {
          .name = "wps-button",
          .parent = &myboard_keys_node,
          .properties = myboard_wps_button_props,
  };

LED property는 `label`, `linux,default-trigger`, `gpios`를 가지며 GPIO reference는 controller node, offset 42, `GPIO_ACTIVE_HIGH`를 지정합니다. `status-led` child node는 `myboard-leds` parent와 이 property array를 연결합니다.

Button property는 `label`, `linux,code`, `gpios`를 가지며 controller node의 offset 15와 `GPIO_ACTIVE_LOW`를 참조합니다. `wps-button` child node는 `myboard-keys` parent에 속합니다.

3단계: Node group 등록

유지보수를 위해 모든 software node를 하나의 array로 묶고 한 번의 호출로 등록하는 것이 좋습니다.

.. code-block:: c

  static const struct software_node * const myboard_swnodes[] = {
          &myboard_gpio_controller_node,
          &myboard_leds_node,
          &myboard_status_led_swnode,
          &myboard_keys_node,
          &myboard_wps_button_swnode,
          NULL
  };

  static int __init myboard_init(void)
  {
          int error;

          error = software_node_register_node_group(myboard_swnodes);
          if (error) {
                  pr_err("Failed to register software nodes: %d\n", error);
                  return error;
          }

          // ... platform device registration follows
  }

Array에는 controller node, LED parent와 child, key parent와 child를 순서대로 넣고 `NULL`로 끝냅니다. `software_node_register_node_group()`이 실패하면 error를 출력하고 그대로 반환합니다.

Device별로 node 등록을 나눈다면 GPIO controller를 나타내는 software node를 이를 reference하는 어느 node보다 먼저 등록해야 합니다.

4단계: Platform device와 software node 연결

마지막으로 platform device를 등록하면서 `struct platform_device_info`의 `fwnode` field로 각 software node를 연결합니다.

.. code-block:: c

  static struct platform_device *leds_pdev;
  static struct platform_device *keys_pdev;

  static int __init myboard_init(void)
  {
          struct platform_device_info pdev_info;
          int error;

          error = software_node_register_node_group(myboard_swnodes);
          if (error)
                  return error;

          memset(&pdev_info, 0, sizeof(pdev_info));
          pdev_info.name = "leds-gpio";
          pdev_info.id = PLATFORM_DEVID_NONE;
          pdev_info.fwnode = software_node_fwnode(&myboard_leds_node);
          leds_pdev = platform_device_register_full(&pdev_info);
          if (IS_ERR(leds_pdev)) {
                  error = PTR_ERR(leds_pdev);
                  goto err_unregister_nodes;
          }

          memset(&pdev_info, 0, sizeof(pdev_info));
          pdev_info.name = "gpio-keys";
          pdev_info.id = PLATFORM_DEVID_NONE;
          pdev_info.fwnode = software_node_fwnode(&myboard_keys_node);
          keys_pdev = platform_device_register_full(&pdev_info);
          if (IS_ERR(keys_pdev)) {
                  error = PTR_ERR(keys_pdev);
                  platform_device_unregister(leds_pdev);
                  goto err_unregister_nodes;
          }

          return 0;

  err_unregister_nodes:
          software_node_unregister_node_group(myboard_swnodes);
          return error;
  }

  static void __exit myboard_exit(void)
  {
          platform_device_unregister(keys_pdev);
          platform_device_unregister(leds_pdev);
          software_node_unregister_node_group(myboard_swnodes);
  }

먼저 node group을 등록한 뒤 `leds-gpio`의 `pdev_info.fwnode`에 `myboard_leds_node`의 fwnode를 지정하고 `platform_device_register_full()`을 호출합니다. 실패하면 node group을 unregister합니다.

이어서 `gpio-keys` device를 `myboard_keys_node`와 연결합니다. 두 번째 등록이 실패하면 먼저 등록한 LED platform device도 unregister한 뒤 node group을 정리합니다.

정상 종료 path에서는 key device, LED device, software-node group 순으로 unregister합니다. 이 변경으로 generic `leds-gpio`와 `gpio-keys` driver가 성공적으로 probe하고 software-node property에서 configuration을 얻으므로 board-specific platform data가 필요 없어집니다.