Android架構分析之硬件抽象層(HAL)

Android版本：2.3.7_r1

Linux內核版本：android-goldfish-2.6.29

一、硬件抽象層核心數據結構

Android硬件抽象層有三個核心數據結構,分別是hw_module_t , hw_module_methods_t, hw_device_t。定義在hardware/libhardware/include/hardware/hardware.h文件中：

[cpp]
40/**
 41 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 42 * and the fields of this data structure must begin with hw_module_t
 43 * followed by module specific information.
 44 */ 
 45typedef struct hw_module_t { 
 46    /** tag must be initialized to HARDWARE_MODULE_TAG */ 
 47    uint32_t tag; 
 48 
 49    /** major version number for the module */ 
 50    uint16_t version_major; 
 51 
 52    /** minor version number of the module */ 
 53    uint16_t version_minor; 
 54 
 55    /** Identifier of module */ 
 56    const char *id; 
 57 
 58    /** Name of this module */ 
 59    const char *name; 
 60 
 61    /** Author/owner/implementor of the module */ 
 62    const char *author; 
 63 
 64    /** Modules methods */ 
 65    struct hw_module_methods_t* methods; 
 66 
 67    /** module's dso */ 
 68    void* dso; 
 69 
 70    /** padding to 128 bytes, reserved for future use */ 
 71    uint32_t reserved[32-7]; 
 72 
 73} hw_module_t; 
 74 
 75typedef struct hw_module_methods_t { 
 76    /** Open a specific device */ 
 77    int (*open)(const struct hw_module_t* module, const char* id, 
 78            struct hw_device_t** device); 
 79 
 80} hw_module_methods_t; 
 81 
 82/**
 83 * Every device data structure must begin with hw_device_t
 84 * followed by module specific public methods and attributes.
 85 */ 
 86typedef struct hw_device_t { 
 87    /** tag must be initialized to HARDWARE_DEVICE_TAG */ 
 88    uint32_t tag; 
 89 
 90    /** version number for hw_device_t */ 
 91    uint32_t version; 
 92 
 93    /** reference to the module this device belongs to */ 
 94    struct hw_module_t* module; 
 95 
 96    /** padding reserved for future use */ 
 97    uint32_t reserved[12]; 
 98 
 99    /** Close this device */ 
100    int (*close)(struct hw_device_t* device); 
101 
102} hw_device_t; 

 40/**
 41 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 42 * and the fields of this data structure must begin with hw_module_t
 43 * followed by module specific information.
 44 */
 45typedef struct hw_module_t {
 46    /** tag must be initialized to HARDWARE_MODULE_TAG */
 47    uint32_t tag;
 48
 49    /** major version number for the module */
 50    uint16_t version_major;
 51
 52    /** minor version number of the module */
 53    uint16_t version_minor;
 54
 55    /** Identifier of module */
 56    const char *id;
 57
 58    /** Name of this module */
 59    const char *name;
 60
 61    /** Author/owner/implementor of the module */
 62    const char *author;
 63
 64    /** Modules methods */
 65    struct hw_module_methods_t* methods;
 66
 67    /** module's dso */
 68    void* dso;
 69
 70    /** padding to 128 bytes, reserved for future use */
 71    uint32_t reserved[32-7];
 72
 73} hw_module_t;
 74
 75typedef struct hw_module_methods_t {
 76    /** Open a specific device */
 77    int (*open)(const struct hw_module_t* module, const char* id,
 78            struct hw_device_t** device);
 79
 80} hw_module_methods_t;
 81
 82/**
 83 * Every device data structure must begin with hw_device_t
 84 * followed by module specific public methods and attributes.
 85 */
 86typedef struct hw_device_t {
 87    /** tag must be initialized to HARDWARE_DEVICE_TAG */
 88    uint32_t tag;
 89
 90    /** version number for hw_device_t */
 91    uint32_t version;
 92
 93    /** reference to the module this device belongs to */
 94    struct hw_module_t* module;
 95
 96    /** padding reserved for future use */
 97    uint32_t reserved[12];
 98
 99    /** Close this device */
100    int (*close)(struct hw_device_t* device);
101
102} hw_device_t;
40-44行，注意這段說明文字，硬件抽象層HAL由一個一個的模塊組成，Android規定，每一個模塊都是一個命名為HAL_MODULE_INFO_SYM的自定義結構體，並且該結構體的第一個成員必須為hw_module_t類型的變量，其它成員變量根據需要由開發者設置。

82-85行，注意這段說明文字，每個設備對應一個自定義結構體，該結構體的第一個成員必須為hw_device_t，其它成員根據需要由開發者設置。

例如，sensor模塊對應的結構體定義在hardware/libhardware/include/hardware/sensors.h文件中：

[cpp]
?344/**
345 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
346 * and the fields of this data structure must begin with hw_module_t
347 * followed by module specific information.
348 */ 
349struct sensors_module_t { 
350    struct hw_module_t common; 
351 
352    /**
353     * Enumerate all available sensors. The list is returned in "list".
354     * @return number of sensors in the list
355     */ 
356    int (*get_sensors_list)(struct sensors_module_t* module, 
357            struct sensor_t const** list); 
358}; 
sensor設備對應的結構體如下： 
392/**
393 * Every device data structure must begin with hw_device_t
394 * followed by module specific public methods and attributes.
395 */ 
396struct sensors_poll_device_t { 
397    struct hw_device_t common; 
398 
399    /** Activate/deactivate one sensor.
400     *
401     * @param handle is the handle of the sensor to change.
402     * @param enabled set to 1 to enable, or 0 to disable the sensor.
403     *
404     * @return 0 on success, negative errno code otherwise
405     */ 
406    int (*activate)(struct sensors_poll_device_t *dev, 
407            int handle, int enabled); 
408 
409    /**
410     * Set the delay between sensor events in nanoseconds for a given sensor.
411     * It is an error to set a delay inferior to the value defined by
412     * sensor_t::minDelay. If sensor_t::minDelay is zero, setDelay() is
413     * ignored and returns 0.
414     *
415     * @return 0 if successful, < 0 on error
416     */ 
417    int (*setDelay)(struct sensors_poll_device_t *dev, 
418            int handle, int64_t ns); 
419 
420    /**
421     * Returns an array of sensor data.
422     * This function must block until events are available.
423     *
424     * @return the number of events read on success, or -errno in case of an error.
425     * This function should never return 0 (no event).
426     *
427     */ 
428    int (*poll)(struct sensors_poll_device_t *dev, 
429            sensors_event_t* data, int count); 
430}; 

344/**
345 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
346 * and the fields of this data structure must begin with hw_module_t
347 * followed by module specific information.
348 */
349struct sensors_module_t {
350    struct hw_module_t common;
351
352    /**
353     * Enumerate all available sensors. The list is returned in "list".
354     * @return number of sensors in the list
355     */
356    int (*get_sensors_list)(struct sensors_module_t* module,
357            struct sensor_t const** list);
358};
sensor設備對應的結構體如下：
392/**
393 * Every device data structure must begin with hw_device_t
394 * followed by module specific public methods and attributes.
395 */
396struct sensors_poll_device_t {
397    struct hw_device_t common;
398
399    /** Activate/deactivate one sensor.
400     *
401     * @param handle is the handle of the sensor to change.
402     * @param enabled set to 1 to enable, or 0 to disable the sensor.
403     *
404     * @return 0 on success, negative errno code otherwise
405     */
406    int (*activate)(struct sensors_poll_device_t *dev,
407            int handle, int enabled);
408
409    /**
410     * Set the delay between sensor events in nanoseconds for a given sensor.
411     * It is an error to set a delay inferior to the value defined by
412     * sensor_t::minDelay. If sensor_t::minDelay is zero, setDelay() is
413     * ignored and returns 0.
414     *
415     * @return 0 if successful, < 0 on error
416     */
417    int (*setDelay)(struct sensors_poll_device_t *dev,
418            int handle, int64_t ns);
419
420    /**
421     * Returns an array of sensor data.
422     * This function must block until events are available.
423     *
424     * @return the number of events read on success, or -errno in case of an error.
425     * This function should never return 0 (no event).
426     *
427     */
428    int (*poll)(struct sensors_poll_device_t *dev,
429            sensors_event_t* data, int count);
430};
對於三星公司的crespo(Nexus S的開發代號)，其sensor模塊的真正實現代碼定義在device/samsung/crespo/libsensors/sensors.cpp文件中：

[cpp]
108static struct hw_module_methods_t sensors_module_methods = { 
109        open: open_sensors 
110}; 
111 
112struct sensors_module_t HAL_MODULE_INFO_SYM = { 
113        common: { 
114                tag: HARDWARE_MODULE_TAG, 
115                version_major: 1, 
116                version_minor: 0, 
117                id: SENSORS_HARDWARE_MODULE_ID, 
118                name: "Samsung Sensor module", 
119                author: "Samsung Electronic Company", 
120                methods: &sensors_module_methods, 
121        }, 
122        get_sensors_list: sensors__get_sensors_list, 
123}; 

108static struct hw_module_methods_t sensors_module_methods = {
109        open: open_sensors
110};
111
112struct sensors_module_t HAL_MODULE_INFO_SYM = {
113        common: {
114                tag: HARDWARE_MODULE_TAG,
115                version_major: 1,
116                version_minor: 0,
117                id: SENSORS_HARDWARE_MODULE_ID,
118                name: "Samsung Sensor module",
119                author: "Samsung Electronic Company",
120                methods: &sensors_module_methods,
121        },
122        get_sensors_list: sensors__get_sensors_list,
123};而在open_sensors函數中，對相應設備對應的sensors_poll_device_t結構進行了賦值：

[cpp]
305/** Open a new instance of a sensor device using name */ 
306static int open_sensors(const struct hw_module_t* module, const char* id, 
307                        struct hw_device_t** device) 
308{ 
309        int status = -EINVAL; 
310        sensors_poll_context_t *dev = new sensors_poll_context_t(); 
311 
312        memset(&dev->device, 0, sizeof(sensors_poll_device_t)); 
313 
314        dev->device.common.tag = HARDWARE_DEVICE_TAG; 
315        dev->device.common.version  = 0; 
316        dev->device.common.module   = const_cast<hw_module_t*>(module); 
317        dev->device.common.close    = poll__close; 
318        dev->device.activate        = poll__activate; 
319        dev->device.setDelay        = poll__setDelay; 
320        dev->device.poll            = poll__poll; 
321 
322        *device = &dev->device.common; 
323        status = 0; 
324 
325        return status; 
326} 

305/** Open a new instance of a sensor device using name */
306static int open_sensors(const struct hw_module_t* module, const char* id,
307                        struct hw_device_t** device)
308{
309        int status = -EINVAL;
310        sensors_poll_context_t *dev = new sensors_poll_context_t();
311
312        memset(&dev->device, 0, sizeof(sensors_poll_device_t));
313
314        dev->device.common.tag = HARDWARE_DEVICE_TAG;
315        dev->device.common.version  = 0;
316        dev->device.common.module   = const_cast<hw_module_t*>(module);
317        dev->device.common.close    = poll__close;
318        dev->device.activate        = poll__activate;
319        dev->device.setDelay        = poll__setDelay;
320        dev->device.poll            = poll__poll;
321
322        *device = &dev->device.common;
323        status = 0;
324
325        return status;
326}
poll__close、poll__activate、poll__setDelay、poll__poll等函數也是在該文件中實現。

二、Android如何使用硬件抽象層

硬件抽象層的作用是對上層Application Framework屏蔽Linux底層驅動程序，那麼Application Framework與硬件抽象層通信的接口是誰呢？答案是hw_get_module函數，該函數定義在hardware/libhardware/hardware.c文件中：

[cpp]
120int hw_get_module(const char *id, const struct hw_module_t **module) 
121{ 
122    int status; 
123    int i; 
124    const struct hw_module_t *hmi = NULL; 
125    char prop[PATH_MAX]; 
126    char path[PATH_MAX]; 
127 
128    /*
129     * Here we rely on the fact that calling dlopen multiple times on
130     * the same .so will simply increment a refcount (and not load
131     * a new copy of the library).
132     * We also assume that dlopen() is thread-safe.
133     */ 
134 
135    /* Loop through the configuration variants looking for a module */ 
136    for (i=0 ; i<HAL_VARIANT_KEYS_COUNT+1 ; i++) { 
137        if (i < HAL_VARIANT_KEYS_COUNT) { 
138            if (property_get(variant_keys[i], prop, NULL) == 0) { 
139                continue; 
140            } 
141            snprintf(path, sizeof(path), "%s/%s.%s.so", 
142                    HAL_LIBRARY_PATH1, id, prop); 
143            if (access(path, R_OK) == 0) break; 
144 
145            snprintf(path, sizeof(path), "%s/%s.%s.so", 
146                     HAL_LIBRARY_PATH2, id, prop); 
147            if (access(path, R_OK) == 0) break; 
148        } else { 
149            snprintf(path, sizeof(path), "%s/%s.default.so", 
150                     HAL_LIBRARY_PATH1, id); 
151            if (access(path, R_OK) == 0) break; 
152        } 
153    } 
154 
155    status = -ENOENT; 
156    if (i < HAL_VARIANT_KEYS_COUNT+1) { 
157        /* load the module, if this fails, we're doomed, and we should not try
158         * to load a different variant. */ 
159        status = load(id, path, module); 
160    } 
161 
162    return status; 
163} 

120int hw_get_module(const char *id, const struct hw_module_t **module)
121{
122    int status;
123    int i;
124    const struct hw_module_t *hmi = NULL;
125    char prop[PATH_MAX];
126    char path[PATH_MAX];
127
128    /*
129     * Here we rely on the fact that calling dlopen multiple times on
130     * the same .so will simply increment a refcount (and not load
131     * a new copy of the library).
132     * We also assume that dlopen() is thread-safe.
133     */
134
135    /* Loop through the configuration variants looking for a module */
136    for (i=0 ; i<HAL_VARIANT_KEYS_COUNT+1 ; i++) {
137        if (i < HAL_VARIANT_KEYS_COUNT) {
138            if (property_get(variant_keys[i], prop, NULL) == 0) {
139                continue;
140            }
141            snprintf(path, sizeof(path), "%s/%s.%s.so",
142                    HAL_LIBRARY_PATH1, id, prop);
143            if (access(path, R_OK) == 0) break;
144
145            snprintf(path, sizeof(path), "%s/%s.%s.so",
146                     HAL_LIBRARY_PATH2, id, prop);
147            if (access(path, R_OK) == 0) break;
148        } else {
149            snprintf(path, sizeof(path), "%s/%s.default.so",
150                     HAL_LIBRARY_PATH1, id);
151            if (access(path, R_OK) == 0) break;
152        }
153    }
154
155    status = -ENOENT;
156    if (i < HAL_VARIANT_KEYS_COUNT+1) {
157        /* load the module, if this fails, we're doomed, and we should not try
158         * to load a different variant. */
159        status = load(id, path, module);
160    }
161
162    return status;
163}
hw_get_module函數的作用是由第一個參數id指定的模塊ID，找到模塊對應的hw_module_t結構體，保存在第二個參數module中。

136-153行，這個for循環是為了獲取模塊名及路徑，保存在path中。循環次數為HAL_VARIANT_KEYS_COUNT次，HAL_VARIANT_KEYS_COUNT是下面要用到的variant_keys數組的數組元素個數。

為了說明這個for循環是如何獲得模塊名及其路徑，我們要先來看一下variant_keys數組的定義，這個數組也是定義在hardware/libhardware/hardware.c文件中：

[cpp]
**
35 * There are a set of variant filename for modules. The form of the filename
36 * is "<MODULE_ID>.variant.so" so for the led module the Dream variants
37 * of base "ro.product.board", "ro.board.platform" and "ro.arch" would be:
38 *
39 * led.trout.so
40 * led.msm7k.so
41 * led.ARMV6.so
42 * led.default.so
43 */ 
44 
45static const char *variant_keys[] = { 
46    "ro.hardware",  /* This goes first so that it can pick up a different
47                       file on the emulator. */ 
48    "ro.product.board", 
49    "ro.board.platform", 
50    "ro.arch" 
51}; 
52 
53static const int HAL_VARIANT_KEYS_COUNT = 
54    (sizeof(variant_keys)/sizeof(variant_keys[0])); 

 34/**
 35 * There are a set of variant filename for modules. The form of the filename
 36 * is "<MODULE_ID>.variant.so" so for the led module the Dream variants
 37 * of base "ro.product.board", "ro.board.platform" and "ro.arch" would be:
 38 *
 39 * led.trout.so
 40 * led.msm7k.so
 41 * led.ARMV6.so
 42 * led.default.so
 43 */
 44
 45static const char *variant_keys[] = {
 46    "ro.hardware",  /* This goes first so that it can pick up a different
 47                       file on the emulator. */
 48    "ro.product.board",
 49    "ro.board.platform",
 50    "ro.arch"
 51};
 52
 53static const int HAL_VARIANT_KEYS_COUNT =
 54    (sizeof(variant_keys)/sizeof(variant_keys[0]));
34-43行，這段注釋說明了模塊對應的動態庫的命名規范。模塊對應的動態庫文件名格式為<MODULE_ID>.variant.so，MODULE_ID是模塊對應的ID，不同模塊對應一個唯一固定的ID，那麼variant是什麼呢？又怎麼獲得variant呢？這就跟下面的variant_keys數組有關了。

45-51行，定義了variant_keys數組，這個數組有4個成員，即指向“ro.hardware”、“ ro.product.board”、“ ro.board.platform”、“ ro.arch”四個字符串的指針。我們可以將“ro.hardware”、“ ro.product.board”、“ ro.board.platform”、“ ro.arch”理解為屬性，系統會通過適當的方法，根據平台、架構等給這些屬性賦值。

例如，“ro.hardware”屬性的屬性值是在系統啟動時由init進程負責設置的。它首先會讀取/proc/cmdline文件，檢查裡面有沒有一個名為androidboot.hardware的屬性，如果有，就把它的值賦值給“ro.hardware”，否則，就將/proc/cpuinfo文件的內容讀取出來，並解析出Haredware字段的內容賦值給“ro.hardware”。例如在Android模擬器中，從/proc/cpuinfo文件中讀取出來的Hardware字段內容為goldfish，於是，init進程就會將 “ro.hardware” 屬性設置為goldfish。

“ ro.product.board”、“ ro.board.platform”、“ ro.arch”屬性是從/system/build.prop文件讀取出來的。/system/build.prop文件是由編譯系統中的編譯腳本build/core/Makefile和shell腳本build/tools/buildinfo.sh生成的，這裡不再詳細分析。

53-54行，定義了HAL_VARIANT_KEYS_COUNT變量，它是variant_keys數組的大小。

從上面我們已經知道了variant_keys數組的內容，也知道了模塊對應的動態庫的命名規范。現在我們的問題是模塊動態庫命名規范格式<MODULE_ID>.variant.so中的variant是怎樣獲得的？又跟variant_keys數組有什麼關系？為了回答這個問題，我們再回到hw_get_module函數的定義。

hw_get_module函數第138行，調用property_get(variant_keys[i], prop, NULL)函數，其作用是取得variant_keys[i]對應的屬性值，保存在prop中。也就是說，在第1次循環時，是取得variant_keys[0]即“ro.hardware”對應的屬性值，保存在prop中，如果沒有取得到，property_get函數會返回0，則進入下一次循環，依次嘗試取得“ ro.product.board”、“ ro.board.platform”、“ ro.arch”對應的屬性值，保存在prop中。如果取得了某個variant_keys[i]對應的屬性值，則在hw_get_module函數第141-142行，按<MODULE_ID>.variant.so規范，得到模塊動態庫的名字及路徑，其中variant就是我們前面得到的prop的值。

hw_get_module函數第148-153行，如果沒有找到variant_keys[i]對應的屬性，則使用<MODULE_ID>.default.so。

hw_get_module函數第156-160行，調用load(id, path, module)導入模塊動態庫，將模塊對應的hw_module_t結構體，保存在module變量中。load函數也定義在hardware/libhardware/hardware.c文件中：

[cpp]
 56/**
 57 * Load the file defined by the variant and if successful
 58 * return the dlopen handle and the hmi.
 59 * @return 0 = success, !0 = failure.
 60 */ 
 61static int load(const char *id, 
 62        const char *path, 
 63        const struct hw_module_t **pHmi) 
 64{ 
 65    int status; 
 66    void *handle; 
 67    struct hw_module_t *hmi; 
 68 
 69    /*
 70     * load the symbols resolving undefined symbols before
 71     * dlopen returns. Since RTLD_GLOBAL is not or'd in with
 72     * RTLD_NOW the external symbols will not be global
 73     */ 
 74    handle = dlopen(path, RTLD_NOW); 
 75    if (handle == NULL) { 
 76        char const *err_str = dlerror(); 
 77        LOGE("load: module=%s\n%s", path, err_str?err_str:"unknown"); 
 78        status = -EINVAL; 
 79        goto done; 
 80    } 
 81 
 82    /* Get the address of the struct hal_module_info. */ 
 83    const char *sym = HAL_MODULE_INFO_SYM_AS_STR; 
 84    hmi = (struct hw_module_t *)dlsym(handle, sym); 
 85    if (hmi == NULL) { 
 86        LOGE("load: couldn't find symbol %s", sym); 
 87        status = -EINVAL; 
 88        goto done; 
 89    } 
 90 
 91    /* Check that the id matches */ 
 92    if (strcmp(id, hmi->id) != 0) { 
 93        LOGE("load: id=%s != hmi->id=%s", id, hmi->id); 
 94        status = -EINVAL; 
 95        goto done; 
 96    } 
 97 
 98    hmi->dso = handle; 
 99 
100    /* success */ 
101    status = 0; 
102 
103    done: 
104    if (status != 0) { 
105        hmi = NULL; 
106        if (handle != NULL) { 
107            dlclose(handle); 
108            handle = NULL; 
109        } 
110    } else { 
111        LOGV("loaded HAL id=%s path=%s hmi=%p handle=%p", 
112                id, path, *pHmi, handle); 
113    } 
114 
115    *pHmi = hmi; 
116 
117    return status; 
118} 

 56/**
 57 * Load the file defined by the variant and if successful
 58 * return the dlopen handle and the hmi.
 59 * @return 0 = success, !0 = failure.
 60 */
 61static int load(const char *id,
 62        const char *path,
 63        const struct hw_module_t **pHmi)
 64{
 65    int status;
 66    void *handle;
 67    struct hw_module_t *hmi;
 68
 69    /*
 70     * load the symbols resolving undefined symbols before
 71     * dlopen returns. Since RTLD_GLOBAL is not or'd in with
 72     * RTLD_NOW the external symbols will not be global
 73     */
 74    handle = dlopen(path, RTLD_NOW);
 75    if (handle == NULL) {
 76        char const *err_str = dlerror();
 77        LOGE("load: module=%s\n%s", path, err_str?err_str:"unknown");
 78        status = -EINVAL;
 79        goto done;
 80    }
 81
 82    /* Get the address of the struct hal_module_info. */
 83    const char *sym = HAL_MODULE_INFO_SYM_AS_STR;
 84    hmi = (struct hw_module_t *)dlsym(handle, sym);
 85    if (hmi == NULL) {
 86        LOGE("load: couldn't find symbol %s", sym);
 87        status = -EINVAL;
 88        goto done;
 89    }
 90
 91    /* Check that the id matches */
 92    if (strcmp(id, hmi->id) != 0) {
 93        LOGE("load: id=%s != hmi->id=%s", id, hmi->id);
 94        status = -EINVAL;
 95        goto done;
 96    }
 97
 98    hmi->dso = handle;
 99
100    /* success */
101    status = 0;
102
103    done:
104    if (status != 0) {
105        hmi = NULL;
106        if (handle != NULL) {
107            dlclose(handle);
108            handle = NULL;
109        }
110    } else {
111        LOGV("loaded HAL id=%s path=%s hmi=%p handle=%p",
112                id, path, *pHmi, handle);
113    }
114
115    *pHmi = hmi;
116
117    return status;
118}
第74行，調用dlopen(path, RTLD_NOW)導入path指定的模塊動態庫。

第83-84行，通過dlsym函數取得HAL_MODULE_INFO_SYM_AS_STR指定的變量的地址，這個地址就是模塊對應的自定義結構體地址。

第115行，將hw_module_t結構賦值給傳遞進來的參數pHmi，即返回給上層調用函數。

分析到這裡，我們可以看出，通過hw_get_module函數，Application Framework代碼可以通過指定的模塊ID找到模塊hw_module_t結構體。有了hw_module_t結構體，就可以調用hw_module_t-> methods->open函數，在open函數中，完成對設備對應的hw_device_t結構體的初始化，並指定設備相關的自定義函數。