mk-ccs-regs register definition generator

실행 환경과 CLI option

이 파일은 warning을 켠 Perl script이며 `GPL-2.0-only OR BSD-3-Clause` 이중 라이선스로 배포됩니다. `Getopt::Long`은 option 대소문자를 구분하고, `File::Basename`은 출력 파일명으로 header guard를 만들 때 사용합니다.

입력 `ccs-regs.asc`는 기본값이 있지만 header, limit C source, limit header는 필수입니다. 필수값이 없거나 `-h`가 지정되면 help를 출력하고 종료합니다. `-r` register description array는 선택 사항이고 `-k`는 kernel space용 type·macro를 생성합니다. Option parsing 실패 시 `can't parse options` 오류로 중단합니다.

#!/usr/bin/perl -w
# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
# Copyright (C) 2019--2020 Intel Corporation

use Getopt::Long qw(:config no_ignore_case);
use File::Basename;

my $ccsregs = "ccs-regs.asc";
my $header;
my $regarray;
my $limitc;
my $limith;
my $kernel;
my $help;

GetOptions("ccsregs|c=s" => \$ccsregs,
           "header|e=s" => \$header,
           "regarray|r=s" => \$regarray,
           "limitc|l=s" => \$limitc,
           "limith|L=s" => \$limith,
           "kernel|k" => \$kernel,
           "help|h" => \$help) or die "can't parse options";

$help = 1 if ! defined $header || ! defined $limitc || ! defined $limith;

if (defined $help) {
        print <<EOH
$0 - Create CCS register definitions for C

usage: $0 -c ccs-regs.asc -e header -r regarray -l limit-c -L limit-header [-k]

        -c ccs register file
        -e header file name
        -r register description array file name
        -l limit and capability array file name
        -L limit and capability header file name
        -k generate files for kernel space consumption
EOH
          ;

출력 mode, 파일 준비와 limit 판별

Kernel mode가 아니면 limit header는 `ccs-os.h`, `uint32_t`, `uint16_t`를 사용합니다. Kernel mode에서는 `linux/bits.h`, `linux/types.h`, `u32`, `u16`으로 바뀝니다.

Script는 입력 register file을 읽기 mode로 열고 register header, 선택적 register array, limit C source, limit header를 쓰기 mode로 엽니다. 어느 파일이든 열 수 없으면 해당 `can't open` 오류로 즉시 중단합니다.

`is_limit_reg()`은 주소가 `0x40` 미만인 status register와 `0x100` 이상 `0xfff` 미만인 configuration register를 제외합니다. 나머지만 limit·capability register로 취급합니다. 생성물에는 동일한 SPDX license와 copyright, 생성 script 이름, 직접 수정하지 말라는 note를 기록합니다.

        exit 0;
}

my $lh_hdr = ! defined $kernel
        ? '#include "ccs-os.h"' . "\n"
        : "#include <linux/bits.h>\n#include <linux/types.h>\n";
my $uint32_t = ! defined $kernel ? 'uint32_t' : 'u32';
my $uint16_t = ! defined $kernel ? 'uint16_t' : 'u16';

open(my $R, "< $ccsregs") or die "can't open $ccsregs";

open(my $H, "> $header") or die "can't open $header";
my $A;
if (defined $regarray) {
        open($A, "> $regarray") or die "can't open $regarray";
}
open(my $LC, "> $limitc") or die "can't open $limitc";
open(my $LH, "> $limith") or die "can't open $limith";

my %this;

sub is_limit_reg($) {
        my $addr = hex $_[0];

        return 0 if $addr < 0x40; # weed out status registers
        return 0 if $addr >= 0x100 && $addr < 0xfff; # weed out configuration registers

        return 1;
}

my $uc_header = basename uc $header;
$uc_header =~ s/[^A-Z0-9]/_/g;

my $copyright = "/* Copyright (C) 2019--2020 Intel Corporation */\n";
my $license = "SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause";
my $note = "/*\n * Generated by $0;\n * do not modify.\n */\n";

for my $fh ($A, $LC) {
        print $fh "// $license\n$copyright$note\n" if defined $fh;
}

Header preamble과 register flag encoding

Register header와 limit header에는 license·copyright·generated note를 쓰고, 출력 파일명을 대문자화한 include guard를 만듭니다. Kernel mode의 register header는 `linux/bits.h`와 `media/v4l2-cci.h`를 include합니다.

`CCS_FL_BASE`는 user-space에서 bit 16, kernel에서 `CCI_REG_PRIVATE_SHIFT`를 기준으로 합니다. `bit_def()`은 kernel이면 `BIT()` 또는 이미 식인 경우 `BIT식`을, user-space이면 `(1U << bit)`를 생성합니다.

`flag_str()`은 다음 private flag bit를 할당하고 전체 check 식에 OR로 누적합니다. User-space는 16·32비트 폭 flag도 만들고, 양쪽 mode 모두 `FLOAT_IREAL`, `IREAL` flag를 만듭니다. Kernel mode는 `BUILD_BUG_ON`으로 누적 flag가 `CCI_REG_PRIVATE_MASK`를 넘지 않는지 검사합니다.

for my $fh ($H, $LH) {
        print $fh "/* $license */\n$copyright$note\n";
}

print $H <<EOF
#ifndef __${uc_header}__
#define __${uc_header}__

EOF
  ;

print $H <<EOF
#include <linux/bits.h>

#include <media/v4l2-cci.h>

EOF
        if defined $kernel;

print $H "#define CCS_FL_BASE                " .
    (defined $kernel ? "CCI_REG_PRIVATE_SHIFT" : 16) . "\n";

my $flag = -1;
my $all_flags;

sub bit_def($) {
        my $bit = shift @_;

        if (defined $kernel) {
                return "BIT$bit" if $bit =~ /^\(.*\)$/;
                return "BIT($bit)";
        }
        return "(1U << $bit)";
}

sub flag_str($$) {
        my ($flag, $check) = @_;

        $$flag++;

        my $flag_str = !$$flag ? "CCS_FL_BASE" : "(CCS_FL_BASE + $$flag)";

        $flag_str = bit_def($flag_str);

        $$check .= " | " if defined $$check;

        $$check .= $flag_str;

        return $flag_str;
}

if (! defined $kernel) {
        print $H "#define CCS_FL_16BIT                " . flag_str(\$flag, \$all_flags) . "\n";
        print $H "#define CCS_FL_32BIT                " . flag_str(\$flag, \$all_flags) . "\n";
}

print $H "#define CCS_FL_FLOAT_IREAL        " . flag_str(\$flag, \$all_flags) . "\n";
print $H "#define CCS_FL_IREAL                " . flag_str(\$flag, \$all_flags) . "\n";
print $H "#define CCS_BUILD_BUG \\
        BUILD_BUG_ON(~CCI_REG_PRIVATE_MASK & ($all_flags))\n"
    if defined $kernel;

생성되는 C structure와 배열 시작

User-space register header는 `CCS_R_ADDR(r)`로 하위 16비트 주소를 추출합니다. 선택적 register array source는 표준 정수 type, stdio, `ccs-extra.h`, `ccs-regs.h`를 include합니다.

Limit header는 kernel 또는 OS abstraction include 뒤에 `struct ccs_limit`을 정의합니다. 각 entry는 register 값, byte 크기, flag와 이름을 가지며, `CCS_L_FL_SAME_REG`는 불연속 index 구간이 같은 실제 register를 가리킴을 표시합니다.

Limit C source는 `ccs-limits.h`, `ccs-regs.h`를 include하고 `ccs_limits[]` 초기화를 시작합니다. 동시에 limit index counter, argument descriptor text, `ccs_reg_desc[]` 출력 buffer를 준비합니다.

print $H <<EOF

#define CCS_R_ADDR(r)                ((r) & 0xffff)

EOF
    if ! defined $kernel;

print $A <<EOF
#include <stdint.h>
#include <stdio.h>
#include "ccs-extra.h"
#include "ccs-regs.h"

EOF
        if defined $A;

my $uc_limith = basename uc $limith;
$uc_limith =~ s/[^A-Z0-9]/_/g;

print $LH <<EOF
#ifndef __${uc_limith}__
#define __${uc_limith}__

$lh_hdr
struct ccs_limit {
        $uint32_t reg;
        $uint16_t size;
        $uint16_t flags;
        const char *name;
};

EOF
  ;
print $LH "#define CCS_L_FL_SAME_REG        " . bit_def(0) . "\n\n";

print $LH <<EOF
extern const struct ccs_limit ccs_limits[];

EOF
  ;

print $LC <<EOF
#include "ccs-limits.h"
#include "ccs-regs.h"

const struct ccs_limit ccs_limits[] = {
EOF
  ;

my $limitcount = 0;
my $argdescs;
my $reglist = "const struct ccs_reg_desc ccs_reg_desc[] = {\n";

이름·공백·크기 helper

`name_split()`은 `name(arg, ...)` 형식에서 기본 이름과 argument 목록을 분리하고 괄호를 제거합니다. Argument 안의 slash는 생성 문자열에서 안전하도록 escape합니다.

`tabconv()`은 8개 공백 묶음을 tab으로 바꾸고 tab 뒤의 불필요한 공백을 제거해 생성 C code를 정렬합니다. `elem_bits()`은 flag에 16 또는 32가 있으면 해당 폭을 반환하고, 없으면 기본 8비트를 반환합니다.

`arr_size()`는 register element byte 크기에 각 argument의 `(max - min + 1)`을 모두 곱해 전체 배열 byte 크기를 계산합니다.

sub name_split($$) {
        my ($name, $addr) = @_;
        my $args;

        $name =~ /([^\(]+?)(\(.*)/;
        ($name, $args) = ($1, $2);
        $args = [split /,\s*/, $args];
        foreach my $t (@$args) {
                $t =~ s/[\(\)]//g;
                $t =~ s/\//\\\//g;
        }

        return ($name, $addr, $args);
}

sub tabconv($) {
        $_ = shift;

        my @l = split "\n", $_;

        map {
                s/ {8,8}/\t/g;
                s/\t\K +//;
        } @l;

        return (join "\n", @l) . "\n";
}

sub elem_bits(@) {
        my @flags = @_;

        return 16 if grep /^16$/, @flags;
        return 32 if grep /^32$/, @flags;
        return 8;
}

sub arr_size($) {
        my $this = $_[0];
        my $size = $this->{elsize};
        my $h = $this->{argparams};

        foreach my $arg (@{$this->{args}}) {
                my $apref = $h->{$arg};

                $size *= $apref->{max} - $apref->{min} + 1;
        }

        return $size;
}

Argument descriptor와 limit entry 생성

`print_args()`는 indexed register의 argument metadata를 C array로 출력합니다. 크기 순으로 정렬된 argument마다 이름, 최소값, 최대값, element stride를 `struct ccs_reg_arg` entry로 만들고 최소 argument 조합을 수집합니다.

이 최소 조합으로 `ccs_reg_desc` entry의 시작 register, 전체 배열 크기, argument 수와 이름을 만듭니다. Limit register이면 `ccs_limits[]` entry도 출력하며, 불연속 구간의 두 번째 조각에는 `CCS_L_FL_SAME_REG`를 설정하고 이름에 실제 limit argument를 덧붙입니다.

sub print_args($$$) {
        my ($this, $postfix, $is_same_reg) = @_;
        my ($args, $argparams, $name) =
          ($this->{args}, $this->{argparams}, $this->{name});
        my $varname = "ccs_reg_arg_" . (lc $name) . $postfix;
        my @mins;
        my @sorted_args = @{$this->{sorted_args}};
        my $lim_arg;
        my $size = arr_size($this);

        $argdescs .= "static const struct ccs_reg_arg " . $varname . "[] = {\n";

        foreach my $sorted_arg (@sorted_args) {
                push @mins, $argparams->{$sorted_arg}->{min};
        }

        foreach my $sorted_arg (@sorted_args) {
                my $h = $argparams->{$sorted_arg};

                $argdescs .= "\t{ \"$sorted_arg\", $h->{min}, $h->{max}, $h->{elsize} },\n";

                $lim_arg .= defined $lim_arg ? ", $h->{min}" : "$h->{min}";
        }

        $argdescs .= "};\n\n";

        $reglist .= "\t{ CCS_R_" . (uc $name) . "(" . (join ",", (@mins)) .
          "), $size, sizeof($varname) / sizeof(*$varname)," .
            " \"" . (lc $name) . "\", $varname },\n";

        print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . "($lim_arg), " .
          $size . ", " . ($is_same_reg ? "CCS_L_FL_SAME_REG" : "0") .
            ", \"$name" . (defined $this->{discontig} ? " $lim_arg" : "") . "\" },\n"
              if is_limit_reg $this->{base_addr};
}

하위 record parser

Main loop는 입력을 한 줄씩 읽어 newline과 선행 공백을 제거하고 `#`, `;`, 빈 줄을 건너뜁니다. `-`로 시작하는 하위 record는 현재 register 문맥에서 type별로 처리합니다.

`- b`는 boolean bit를 `CCS_<REGISTER>_<BIT>` macro로, `- f`는 field의 SHIFT와 MASK macro로, `- e`는 현재 field 또는 register의 enum macro로 변환합니다. 이름의 comma, dot, hyphen은 underscore로 정규화합니다.

`- l`은 indexed argument의 min·max macro와 element stride·불연속 구간을 저장합니다. 16진 min/max는 숫자로 변환하고, 현재 register가 요구하는 모든 argument 정의가 모일 때까지 formula 생성을 미룹니다.

my $hdr_data;

while (<$R>) {
        chop;
        s/^\s*//;
        next if /^[#;]/ || /^$/;
        if (s/^-\s*//) {
                if (s/^b\s*//) {
                        my ($bit, $addr) = split /\t+/;
                        $bit = uc $bit;
                        $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) ."_$bit", bit_def($addr) . "\n";
                } elsif (s/^f\s*//) {
                        s/[,\.-]/_/g;
                        my @a = split /\s+/;
                        my ($msb, $lsb, $this_field) = reverse @a;
                        @a = ( { "name" => "SHIFT", "addr" => $lsb, "fmt" => "%uU", },
                               { "name" => "MASK", "addr" => (1 << ($msb + 1)) - 1 - ((1 << $lsb) - 1), "fmt" => "0x%" . join(".", ($this{"elsize"} >> 2) x 2) . "x" } );
                        $this{"field"} = $this_field;
                        foreach my $ar (@a) {
                                #print $ar->{fmt}."\n";
                                $hdr_data .= sprintf "#define %-62s " . $ar->{"fmt"} . "\n", "CCS_" . (uc $this{"name"}) . (defined $this_field ? "_" . uc $this_field : "") . "_" . $ar->{"name"}, $ar->{"addr"} . "\n";
                        }
                } elsif (s/^e\s*//) {
                        s/[,\.-]/_/g;
                        my ($enum, $addr) = split /\s+/;
                        $enum = uc $enum;
                        $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) . (defined $this{"field"} ? "_" . uc $this{"field"} : "") ."_$enum", $addr . ($addr =~ /0x/i ? "" : "U") . "\n";
                } elsif (s/^l\s*//) {
                        my ($arg, $min, $max, $elsize, @discontig) = split /\s+/;
                        my $size;

                        foreach my $num ($min, $max) {
                                $num = hex $num if $num =~ /0x/i;
                        }

                        $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MIN_$arg"), $min . ($min =~ /0x/i ? "" : "U") . "\n";
                        $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MAX_$arg"), $max . ($max =~ /0x/i ? "" : "U") . "\n";

                        my $h = $this{argparams};

                        $h->{$arg} = { "min" => $min,
                                       "max" => $max,
                                       "elsize" => $elsize =~ /^0x/ ? hex $elsize : $elsize,
                                       "discontig" => \@discontig };

                        $this{discontig} = $arg if @discontig;

                        next if $#{$this{args}} + 1 != scalar keys %{$this{argparams}};

Indexed register와 불연속 주소 공식

모든 argument가 준비되면 parser는 base address에 각 `argument * element size`를 더해 register formula를 만듭니다. 불연속 정보가 있으면 기준보다 작은 index와 큰 index에 서로 다른 offset 공식을 사용합니다. Register flag가 있으면 전체 주소 식을 괄호로 묶고 마지막에 flag를 OR합니다.

생성한 `CCS_R_<NAME>(args)` macro 뒤에 누적된 field·enum macro를 출력합니다. Argument는 comment가 설명하듯 element size의 내림차순으로 정렬합니다.

불연속 argument는 첫 번째 연속 범위와 두 번째 범위로 min/max를 나눠 `print_args()`를 두 번 호출하며, 두 번째 entry는 같은 register를 공유한다고 표시합니다. Limit register에는 argument 조합에서 byte offset을 계산하는 `CCS_L_<NAME>_OFFSET(args)` macro도 생성합니다.

        my $reg_formula = "$this{addr}";
        my $lim_formula;

        chop $reg_formula;

        $reg_formula = "(" . $reg_formula if $this{flagstring} ne "";

        foreach my $arg (@{$this{args}}) {
                my $d = $h->{$arg}->{discontig};
                my $times = $h->{$arg}->{elsize} != 1 ?
                  " * " . $h->{$arg}->{elsize} : "";

                if (@$d) {
                        my ($lim, $offset) = split /,/, $d->[0];

                        $reg_formula .= " + (($arg) < $lim ? ($arg)$times : $offset + (($arg) - $lim)$times)";
                } else {
                        $reg_formula .= " + ($arg)$times";
                }

                $lim_formula .= (defined $lim_formula ? " + " : "") . "($arg)$times";
        }

        $reg_formula .= ")";
        $lim_formula =~ s/^\(([a-z0-9]+)\)$/$1/i;

        print $H tabconv sprintf("#define %-62s %s", "CCS_R_" . (uc $this{name}) .
                                 $this{arglist}, $reg_formula .
                                 (($this{flagstring} eq "") ? "" :
                                  " | " . $this{flagstring} . ")") . "\n");

        print $H tabconv $hdr_data;
        undef $hdr_data;

        # Sort arguments in descending order by size
        @{$this{sorted_args}} = sort {
                $h->{$a}->{elsize} <= $h->{$b}->{elsize}
        } @{$this{args}};

        if (defined $this{discontig}) {
                my $da = $this{argparams}->{$this{discontig}};
                my ($first_discontig) = split /,/, $da->{discontig}->[0];
                my $max = $da->{max};

                $da->{max} = $first_discontig - 1;
                print_args(\%this, "", 0);

                $da->{min} = $da->{max} + 1;
                $da->{max} = $max;
                print_args(\%this, $first_discontig, 1);
        } else {
                print_args(\%this, "", 0);
        }

        next unless is_limit_reg $this{base_addr};

        print $LH tabconv sprintf "#define %-63s%s\n",
          "CCS_L_" . (uc $this{name}) . "_OFFSET(" .
            (join ", ", @{$this{args}}) . ")", "($lim_formula)";
}

최상위 register parser

Argument가 없는 하위 record 처리가 끝나면 누적 header data를 바로 출력합니다. 최상위 register 줄은 name, address와 flag 목록으로 분리하고, 괄호가 있으면 `name_split()`으로 indexed argument를 추출합니다.

Register 폭은 `elem_bits()`로 정하고 user-space에서는 16·32비트 flag를, 양쪽 mode에서는 `float_ireal`과 `ireal` flag를 조합합니다. Kernel mode 주소는 `CCI_REG<bits>(address)`로 감쌉니다.

Argument가 없는 register는 flag를 주소에 즉시 OR하고, indexed register는 formula 생성 단계까지 별도 `flagstring`으로 유지합니다. 정규화한 name, 주소, base address, argument metadata와 element byte 크기를 `%this` 현재-register 상태에 저장합니다.

        if (! @{$this{args}}) {
                print $H tabconv($hdr_data);
                undef $hdr_data;
        }

        next;
}

my ($name, $addr, @flags) = split /\t+/, $_;
my $args = [];

my $sp;

($name, $addr, $args) = name_split($name, $addr) if /\(.*\)/;

$name =~ s/[,\.-]/_/g;

my $flagstring = "";
my $bits = elem_bits(@flags);
if (! defined $kernel) {
        $flagstring .= "| CCS_FL_16BIT " if $bits == 16;
        $flagstring .= "| CCS_FL_32BIT " if $bits == 32;
}
$flagstring .= "| CCS_FL_FLOAT_IREAL " if grep /^float_ireal$/, @flags;
$flagstring .= "| CCS_FL_IREAL " if grep /^ireal$/, @flags;
$flagstring =~ s/^\| //;
$flagstring =~ s/ $//;
$flagstring = "($flagstring)" if $flagstring =~ /\|/;
my $base_addr = $addr;
$addr = "CCI_REG$bits($addr)" if defined $kernel;

if ($flagstring ne "" && !@$args) {
        $addr = "($addr | $flagstring)";
        $flagstring = "";
}

my $arglist = @$args ? "(" . (join ", ", @$args) . ")" : "";
$hdr_data .= sprintf "#define %-62s %s\n", "CCS_R_" . (uc $name), $addr
  if !@$args;

$name =~ s/\(.*//;

%this = ( name => $name,
          addr => $addr,
          flagstring => $flagstring,
          base_addr => $base_addr,
          argparams => {},
          args => $args,
          arglist => $arglist,
          elsize => $bits / 8,
        );

일반 register와 limit index

Argument가 없는 register는 `ccs_reg_desc[]`에 element 하나와 argument 없음으로 기록하고, header macro를 즉시 출력합니다. 주소가 limit 범위이면 `ccs_limits[]`에도 byte 크기와 이름을 추가합니다.

모든 limit register에는 현재 `limitcount`를 값으로 하는 `CCS_L_<NAME>` index macro를 만들고 counter를 증가시킵니다. 이 index는 생성된 `ccs_limits[]` 배열 위치와 일치합니다.

        if (!@$args) {
                $reglist .= "\t{ CCS_R_" . (uc $name) . ", 1,  0, \"" . (lc $name) . "\", NULL },\n";
                print $H tabconv $hdr_data;
                undef $hdr_data;

                print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . ", " .
                  $this{elsize} . ", 0, \"$name\" },\n"
                    if is_limit_reg $this{base_addr};
        }

        print $LH tabconv sprintf "#define %-63s%s\n",
          "CCS_L_" . (uc $this{name}), $limitcount++
            if is_limit_reg $this{base_addr};
}

배열 종료, guard와 file close

Register array 출력이 요청되었다면 먼저 argument descriptor, 이어 register list를 쓰고 `{ 0 }` sentinel로 배열을 끝냅니다. Register header와 limit header는 각각 include guard를 닫습니다.

Limit header의 `CCS_L_LAST`에는 최종 limit count를 기록합니다. Limit C array는 `{ 0 } /* Guardian */` sentinel과 닫는 brace를 출력합니다. 마지막으로 입력, header, 선택적 register array, limit C와 limit header handle을 모두 닫습니다.

if (defined $A) {
        print $A $argdescs, $reglist;

        print $A "\t{ 0 }\n";

        print $A "};\n";
}

print $H "\n#endif /* __${uc_header}__ */\n";

print $LH tabconv sprintf "#define %-63s%s\n", "CCS_L_LAST", $limitcount;

print $LH "\n#endif /* __${uc_limith}__ */\n";

print $LC "\t{ 0 } /* Guardian */\n";
print $LC "};\n";

close($R);
close($H);
close($A) if defined $A;
close($LC);
close($LH);