koktoh の雑記帳

気ままに書いていきます

【不定期連載】QMK 探検隊 -その9-

QMK探検隊 自作キーボード 雑記

はじめに

これは、「C言語とか組み込みなんもわからん」男が QMK というジャングルを探検していく、ノンフィクションドキュメンタリーである……
なお、更新は亀の歩みである……

前回のおさらい

koktoh.hatenablog.com

quantum.h の include を順番に探検していたら、 keymap.h もいっぱい include されていたので、順番に探検していたら、 action.c もいっぱい include されていたので、順番に見てきた

探検開始

さて、action.c の include を見てきたので、おおもとの quantum.h の include を見ていこう
次は keymap.h だ

  • wait.h
  • matrix.h
  • keymap.h
  • action_layer.h
  • eeconfig.h
  • bootloader.h
  • timer.h
  • sync_timer.h
  • config_common.h
  • gpio.h
  • atomic_util.h
  • led.h
  • action_util.h
  • action_tapping.h
  • print.h
  • send_string.h
  • suspend.h

keymap.h

github.com

ソース全体

/*
Copyright 2012-2016 Jun Wako <wakojun@gmail.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#pragma once

#include <stdint.h>
#include <stdbool.h>
#include "action.h"
#if defined(__AVR__)
#    include <avr/pgmspace.h>
#elif defined PROTOCOL_CHIBIOS
// We need to ensure that chibios is include before redefining reset
#    include <ch.h>
#endif
#include "keycode.h"
#include "action_macro.h"
#include "report.h"
#include "host.h"
// #include "print.h"
#include "debug.h"
#include "keycode_config.h"

// ChibiOS uses RESET in its FlagStatus enumeration
// Therefore define it as QK_RESET here, to avoid name collision
#if defined(PROTOCOL_CHIBIOS)
#    define RESET QK_RESET
#endif
// Gross hack, remove me and change RESET keycode to QK_BOOT
#if defined(__AVR_AT90USB647__) || defined(__AVR_AT90USB1287__)
#    undef RESET
#endif

#include "quantum_keycodes.h"

// translates key to keycode
uint16_t keymap_key_to_keycode(uint8_t layer, keypos_t key);

// translates function id to action
uint16_t keymap_function_id_to_action(uint16_t function_id);

extern const uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS];
extern const uint16_t fn_actions[];

プロトタイプ宣言や、グローバル変数の宣言が行われている
グローバル変数について見ていこう

extern const uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS];

これに関しては馴染みがあるのではないだろうか
keymap.c で各々がキーマップを定義するときに使っている

./util/new_keyboard.sh を実行すると作成される keymap.c を見てみよう

/* Copyright %YEAR% %YOUR_NAME%
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
#include QMK_KEYBOARD_H

// Defines names for use in layer keycodes and the keymap
enum layer_names {
    _BASE,
    _FN
};

// Defines the keycodes used by our macros in process_record_user
enum custom_keycodes {
    QMKBEST = SAFE_RANGE,
    QMKURL
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    /* Base */
    [_BASE] = LAYOUT(
        KC_A,    KC_1,    MO(_FN),
            KC_TAB,   KC_SPC
    ),
    [_FN] = LAYOUT(
        QMKBEST, QMKURL,  _______,
            RESET,    XXXXXXX
    )
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    switch (keycode) {
        case QMKBEST:
            if (record->event.pressed) {
                // when keycode QMKBEST is pressed
                SEND_STRING("QMK is the best thing ever!");
            } else {
                // when keycode QMKBEST is released
            }
            break;
        case QMKURL:
            if (record->event.pressed) {
                // when keycode QMKURL is pressed
                SEND_STRING("https://qmk.fm/\n");
            } else {
                // when keycode QMKURL is released
            }
            break;
    }
    return true;
}

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    /* Base */
    [_BASE] = LAYOUT(
        KC_A,    KC_1,    MO(_FN),
            KC_TAB,   KC_SPC
    ),
    [_FN] = LAYOUT(
        QMKBEST, QMKURL,  _______,
            RESET,    XXXXXXX
    )
};

ここでキーマップを PROGMEM に保存するようにしている

extern const uint16_t fn_actions[];

こちらは現在ほとんど使われていないようだ
action_code.h で定義されている ACTION_XXXXXX 系を登録するようである

keymap.common.c

github.com

ソース全体

/*
Copyright 2012-2017 Jun Wako <wakojun@gmail.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#include "keymap.h"
#include "report.h"
#include "keycode.h"
#include "action_layer.h"
#if defined(__AVR__)
#    include <util/delay.h>
#    include <stdio.h>
#endif
#include "action.h"
#include "action_macro.h"
#include "debug.h"
#include "quantum.h"

#ifdef BACKLIGHT_ENABLE
#    include "backlight.h"
#endif

#ifdef MIDI_ENABLE
#    include "process_midi.h"
#endif

extern keymap_config_t keymap_config;

#include <inttypes.h>

/* converts key to action */
action_t action_for_key(uint8_t layer, keypos_t key) {
    // 16bit keycodes - important
    uint16_t keycode = keymap_key_to_keycode(layer, key);

    // keycode remapping
    keycode = keycode_config(keycode);

    action_t action = {};
    uint8_t  action_layer, when, mod;

    (void)action_layer;
    (void)when;
    (void)mod;

    switch (keycode) {
        case KC_A ... KC_EXSEL:
        case KC_LCTRL ... KC_RGUI:
            action.code = ACTION_KEY(keycode);
            break;
#ifdef EXTRAKEY_ENABLE
        case KC_SYSTEM_POWER ... KC_SYSTEM_WAKE:
            action.code = ACTION_USAGE_SYSTEM(KEYCODE2SYSTEM(keycode));
            break;
        case KC_AUDIO_MUTE ... KC_BRIGHTNESS_DOWN:
            action.code = ACTION_USAGE_CONSUMER(KEYCODE2CONSUMER(keycode));
            break;
#endif
#ifdef MOUSEKEY_ENABLE
        case KC_MS_UP ... KC_MS_ACCEL2:
            action.code = ACTION_MOUSEKEY(keycode);
            break;
#endif
        case KC_TRNS:
            action.code = ACTION_TRANSPARENT;
            break;
        case QK_MODS ... QK_MODS_MAX:;
            // Has a modifier
            // Split it up
            action.code = ACTION_MODS_KEY(keycode >> 8, keycode & 0xFF);  // adds modifier to key
            break;
#ifndef NO_ACTION_FUNCTION
        case KC_FN0 ... KC_FN31:
            action.code = keymap_function_id_to_action(FN_INDEX(keycode));
            break;
        case QK_FUNCTION ... QK_FUNCTION_MAX:;
            // Is a shortcut for function action_layer, pull last 12bits
            // This means we have 4,096 FN macros at our disposal
            action.code = keymap_function_id_to_action((int)keycode & 0xFFF);
            break;
#endif
#ifndef NO_ACTION_MACRO
        case QK_MACRO ... QK_MACRO_MAX:
            if (keycode & 0x800)  // tap macros have upper bit set
                action.code = ACTION_MACRO_TAP(keycode & 0xFF);
            else
                action.code = ACTION_MACRO(keycode & 0xFF);
            break;
#endif
#ifndef NO_ACTION_LAYER
        case QK_LAYER_TAP ... QK_LAYER_TAP_MAX:
            action.code = ACTION_LAYER_TAP_KEY((keycode >> 0x8) & 0xF, keycode & 0xFF);
            break;
        case QK_TO ... QK_TO_MAX:;
            // Layer set "GOTO"
            when         = (keycode >> 0x4) & 0x3;
            action_layer = keycode & 0xF;
            action.code  = ACTION_LAYER_SET(action_layer, when);
            break;
        case QK_MOMENTARY ... QK_MOMENTARY_MAX:;
            // Momentary action_layer
            action_layer = keycode & 0xFF;
            action.code  = ACTION_LAYER_MOMENTARY(action_layer);
            break;
        case QK_DEF_LAYER ... QK_DEF_LAYER_MAX:;
            // Set default action_layer
            action_layer = keycode & 0xFF;
            action.code  = ACTION_DEFAULT_LAYER_SET(action_layer);
            break;
        case QK_TOGGLE_LAYER ... QK_TOGGLE_LAYER_MAX:;
            // Set toggle
            action_layer = keycode & 0xFF;
            action.code  = ACTION_LAYER_TOGGLE(action_layer);
            break;
#endif
#ifndef NO_ACTION_ONESHOT
        case QK_ONE_SHOT_LAYER ... QK_ONE_SHOT_LAYER_MAX:;
            // OSL(action_layer) - One-shot action_layer
            action_layer = keycode & 0xFF;
            action.code  = ACTION_LAYER_ONESHOT(action_layer);
            break;
        case QK_ONE_SHOT_MOD ... QK_ONE_SHOT_MOD_MAX:;
            // OSM(mod) - One-shot mod
            mod         = mod_config(keycode & 0xFF);
            action.code = ACTION_MODS_ONESHOT(mod);
            break;
#endif
#ifndef NO_ACTION_LAYER
        case QK_LAYER_TAP_TOGGLE ... QK_LAYER_TAP_TOGGLE_MAX:
            action.code = ACTION_LAYER_TAP_TOGGLE(keycode & 0xFF);
            break;
        case QK_LAYER_MOD ... QK_LAYER_MOD_MAX:
            mod          = mod_config(keycode & 0xF);
            action_layer = (keycode >> 4) & 0xF;
            action.code  = ACTION_LAYER_MODS(action_layer, mod);
            break;
#endif
#ifndef NO_ACTION_TAPPING
        case QK_MOD_TAP ... QK_MOD_TAP_MAX:
            mod         = mod_config((keycode >> 0x8) & 0x1F);
            action.code = ACTION_MODS_TAP_KEY(mod, keycode & 0xFF);
            break;
#endif
#ifdef SWAP_HANDS_ENABLE
        case QK_SWAP_HANDS ... QK_SWAP_HANDS_MAX:
            action.code = ACTION(ACT_SWAP_HANDS, keycode & 0xff);
            break;
#endif

        default:
            action.code = ACTION_NO;
            break;
    }
    return action;
}

__attribute__((weak)) const uint16_t PROGMEM fn_actions[] = {

};

/* Macro */
__attribute__((weak)) const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { return MACRO_NONE; }

/* Function */
__attribute__((weak)) void action_function(keyrecord_t *record, uint8_t id, uint8_t opt) {}

// translates key to keycode
__attribute__((weak)) uint16_t keymap_key_to_keycode(uint8_t layer, keypos_t key) {
    // Read entire word (16bits)
    return pgm_read_word(&keymaps[(layer)][(key.row)][(key.col)]);
}

// translates function id to action
__attribute__((weak)) uint16_t keymap_function_id_to_action(uint16_t function_id) {
// The compiler sees the empty (weak) fn_actions and generates a warning
// This function should not be called in that case, so the warning is too strict
// If this function is called however, the keymap should have overridden fn_actions, and then the compile
// is comparing against the wrong array
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Warray-bounds"
    return pgm_read_word(&fn_actions[function_id]);
#pragma GCC diagnostic pop
}

~ 37行

include 宣言である

~ 39行

keymap_config_t 型のグローバル変数 keymap_config を宣言している
keymap_config_t は keycode_config.h で定義されている

github.com

~最終行

各関数について見ていこう
まずは、 keymap.h でプロトタイプ宣言されている関数から見ていく

uint16_t keymap_key_to_keycode(uint8_t layer, keypos_t key)

pgm_read_word というマクロを使用している
これは progmem.h で宣言されている

github.com

これは PROGMEM 上の指定したアドレス address_short の値を読みだすというものらしい
keymap.c で各々が定義した uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS] をもとにキーコードを PROGMEM から読みだしている

uint16_t keymap_function_id_to_action(uint16_t function_id)

keymap_key_to_keycode(uint8_t layer, keypos_t key) と同様に keymap.c で各々が定義した uint16_t fn_actions[] をもとにアクションを PROGMEM から読みだしている

action_t action_for_key(uint8_t layer, keypos_t key)

レイヤとキー位置をもとにキーコードを取得し、キーコードによって action_t に必要な情報を格納して返している
action_t は action_code.h で定義されている

github.com

代表的なアクションを上げると、キーの押す / 離す、レイヤを入れ替える、などだ

まとめ

keymap.h を見てきた
keymap.c で定義した uint16_t keymaps[][MATRIX_ROWS][MATRIX_COLS] を action_t に変換することを役割としていた

次回予告

action_layer.h はすでに探検したので、次回は eeconfig.h から探検していこうと思う

action_layer.h の探検記録

koktoh.hatenablog.com