fuchsia学习-banjo-tutorial.md(上)

banjo教程

本文档是zircon驱动开发套件[Zircon Driver Development Kit]文档的一部分内容。

总览

Banjo是一个转换编码器。一个将fidl定义的接口语言转换成目标语言的程序(例如*.fidl转换成*.c,*.cpp,*.java等)。

详细内容可以参考:

https://fuchsia.googlesource.com/fuchsia/+/master/docs/development/languages/fidl/README.md。

本教程由以下内容构成:

  1. Banjo简要概述
  2. 简单示例(I2C)
  3. 解释从示例到生成代码

同时,这里还包含一些参考,比如:一些内建关键字和原始类型。

概述

Banjo同时生成协议制定者和协议使用者的C和C++代码。

 

示例

第一步,让我们来看一个相对简单的Banjo规范。在文件中zircon/system/banjo/ddk-protocol-i2c/i2c.banjo。

具体代码如下:

[01] // Copyright 2018 The Fuchsia Authors. All rights reserved.
[02] // Use of this source code is governed by a BSD-style license that can be
[03] // found in the LICENSE file.
[04]
[05] library ddk.protocol.i2c;
[06]
[07] using zx;
[08]
[09] const uint32 I2C_10_BIT_ADDR_MASK = 0xF000;
[10] const uint32 I2C_MAX_RW_OPS = 8;
[11]
[12] /// See `Transact` below for usage.
[13] struct I2cOp {
[14]     vector data;
[15]     bool is_read;
[16]     bool stop;
[17] };
[18]
[19] [Layout = "ddk-protocol"]
[20] protocol I2c {
[21]     /// Writes and reads data on an i2c channel. Up to I2C_MAX_RW_OPS operations can be passed in.
[22]     /// For write ops, i2c_op_t.data points to data to write.  The data to write does not need to be
[23]     /// kept alive after this call.  For read ops, i2c_op_t.data is ignored.  Any combination of reads
[24]     /// and writes can be specified.  At least the last op must have the stop flag set.
[25]     /// The results of the operations are returned asynchronously via the transact_cb.
[26]     /// The cookie parameter can be used to pass your own private data to the transact_cb callback.
[27]     [Async]
[28]     Transact(vector op) -> (zx.status status, vector op);
[29]     /// Returns the maximum transfer size for read and write operations on the channel.
[30]     GetMaxTransferSize() -> (zx.status s, usize size);
[31]     GetInterrupt(uint32 flags) -> (zx.status s, handle irq);
[32] };

该文件定义了一个允许应用程序通过I2C总线读写数据的接口。在I2C总线中,必须先写数据到设备请求应答。如果得到了应答,那么就可以从设备读取数据了。

我们来一行一行地看一下这些代码:

第5行,`library`直接告诉Banjo编译器需要添加什么前缀到输出的产物。可以认为它是一个域名识别符。

第7行,`using`直接告诉Banjo编译器去包含’zx’库。

第9~10行,会被程序使用到的两个常量。

第13~17行,定义了一个`I2cOp`结构体,程序会使用该结构体完成和总线的数据发送和接收。

第19~32行,定义了Banjo规范的接口方法。我们会在接口部分内容做更详细的介绍。

不要被21~26行的注释困惑了,它仅仅是注释而已,只不过它用了“///”,普通注释是“//”。它将被生成到目标源码中。在目标源码中“///”会变成“//”。

 

操作结构

在我们I2C例子中,结构体`struct I2cOp`定义了以下三个元素:

元素

类型

使用

Data

Vector

包含发送到总线,并且可以从总线接收的数据

Is_read

Bool

表示读取功能所需的标志

Stop

Bool

操作后应该发送一个表示停止字节所需的标志

 

该结构定义了通信区域,应用于协议实现者(通常是驱动程序)和协议使用者(使用总线的应用程序)。

接口

更有趣的部分内容是’protocol’规范。

我们现在将会跳过19行的`[Layout]`,和27行的`[Async]`属性,不过在后面专讲属性[Attributes]的时候,会反回到这两项内容。

本协议定义了三个接口方法:

* `Transact` ——办理

* `GetMaxTransferSize` ——获取最大传输大小

* `GetInterrupt` ——获取中断

这里并没详细讲解I2C内部操作(毕竟不是I2C总线的教程),直接看他们怎样转换成目标语言的。

我们会分开查看c和c++的实现,使用c语言描述包含结构体的定义和c++是相同的。

>现在支持生成c和c++语言代码,计划将来支持RUST语言。

banjo对应的c语言版本

c语言的实现相对比较直接了当:

* `struct`s和`union`s几乎直接映射到他们的C语言对应关键字

* `enum`s和常量生成为`#define`宏

* `protocol`s生成为两个`struct`s

1、a function table——函数功能表

2、一个指向函数表和上下文的结构体指针

* 也会生成一些辅助函数

c语言版本的文件生成在:

`//zircon/build-`_TARGET_`/system/banjo/ddk-protocol-i2c/gen/include/ddk/protocol/i2c.h`。TARGET是目标架构,比如arm64,x86等。

文件范例

本范例比较长,我们分几个部分来查看。

第一部分,样版头,我们看到之前说的”///”变成了”//”。

[01] // Copyright 2018 The Fuchsia Authors. All rights reserved.
[02] // Use of this source code is governed by a BSD-style license that can be
[03] // found in the LICENSE file.
[04]
[05] // WARNING: THIS FILE IS MACHINE GENERATED. DO NOT EDIT.
[06] //          MODIFY system/banjo/ddk-protocol-i2c/i2c.banjo INSTEAD.
[07]
[08] #pragma once
[09]
[10] #include 
[11] #include 
[12]
[13] __BEGIN_CDECLS

第二部分,进一步声明结构体和函数。

[15] // Forward declarations
[16]
[17] typedef struct i2c_op i2c_op_t;
[18] typedef struct i2c_protocol i2c_protocol_t;
[19] typedef void (*i2c_transact_callback)(void* ctx, zx_status_t status, const i2c_op_t* op_list, size_t op_count);
[20]
[21] // Declarations
[22]
[23] // See `Transact` below for usage.
[24] struct i2c_op {
[25]     const void* data_buffer;
[26]     size_t data_size;
[27]     bool is_read;
[28]     bool stop;
[29] };

注意第17~19行,只声明了类型,并没有定义实际的结构体和该协议类型的函数。

注意文件*.banjo的第12行,经过编译转换后,到生成文件(这里是*.h)的第23行。原banjo文件被去掉了一个’/’符号,使得生成的文件的注释符合常规格式。

生成文件的第24~29行,结构体struct i2c_op几乎是从原banjo文件直接复制映射过来的。

精明的C程序员将立即看到如何在C中处理C ++样式`vector data`(原始`.banjo`文件行`[14]`):它被转换为指针(“`data_buffer`”)和大小(“`data_size`”)。

以命名而言,基础名字是data(由banjo文件提供)。对于voidptr的向量,转译器增加了”_buffer”和”_size”,将向量转换成c语言兼容的结构体。对于其他向量类型,转译器增加”_list”和”_count”作为替换。

第三部分,常量。

接下来,我们看到`const uint32`常量转换成了`#define`语句。如下:

[31] #define I2C_MAX_RW_OPS UINT32_C(8)
[32]
[33]#define I2C_10_BIT_ADDR_MASK UINT32_C(0xF000)

在c语言版本中,我们选择`#define`替换`const uint32_t`的原因:

  1. `#define`语句只存在于编译时间,在使用的地方会被内联使用。
  2. `#define`允许在编译时间做优化处理。(比如,使用常量做数学运算)

缺点是我们没有类型安全性,这就是你看到辅助宏的原因(比如上面的,UINT32_C())。他们只是将常量转换为适当的类型。

 第四部分,协议结构体。

现在进入关键内容:

[35] typedef struct i2c_protocol_ops {
[36]     void (*transact)(void* ctx, const i2c_op_t* op_list, size_t op_count, i2c_transact_callback callback, void* cookie);
[37]     zx_status_t (*get_max_transfer_size)(void* ctx, size_t* out_size);
[38]     zx_status_t (*get_interrupt)(void* ctx, uint32_t flags, zx_handle_t* out_irq);
[39] } i2c_protocol_ops_t;

`typedef`创建了一个包含三个协议方法的结构体定义,这些协议方法是我们之前在banjo文件中定义的,见原banjo文件的第28,30,31行。

注意已经发生重整的名字。这个可以让你怎样把协议方法名字和c语言函数指针映射关系对应起来,以便于知道他们调用的什么。

下一步,接口定义封装在上下文结构中,

[41] struct i2c_protocol {
[42]     i2c_protocol_ops_t* ops;
[43]     void* ctx;
[44] };

现在,banjo中21~26行的注释变得更有意义。

[46] // Writes and reads data on an i2c channel. Up to I2C_MAX_RW_OPS operations can be passed in.
[47] // For write ops, i2c_op_t.data points to data to write.  The data to write does not need to be
[48] // kept alive after this call.  For read ops, i2c_op_t.data is ignored.  Any combination of reads
[49] // and writes can be specified.  At least the last op must have the stop flag set.
[50] // The results of the operations are returned asynchronously via the transact_cb.
[51] // The cookie parameter can be used to pass your own private data to the transact_cb callback.

最后,我们看到实际生成的三个方法的c语言代码:

[52] static inline void i2c_transact(const i2c_protocol_t* proto, const i2c_op_t* op_list, size_t op_count, i2c_transact_callback callback, void* cookie) {
[53]     proto->ops->transact(proto->ctx, op_list, op_count, callback, cookie);
[54] }
[55] // Returns the maximum transfer size for read and write operations on the channel.
[56] static inline zx_status_t i2c_get_max_transfer_size(const i2c_protocol_t* proto, size_t* out_size) {
[57]     return proto->ops->get_max_transfer_size(proto->ctx, out_size);
[58] }
[59] static inline zx_status_t i2c_get_interrupt(const i2c_protocol_t* proto, uint32_t flags, zx_handle_t* out_irq) {
[60]     return proto->ops->get_interrupt(proto->ctx, flags, out_irq);
[61] }

注意`i2c_`的前缀怎么加到方法名字中的(原banjo文件的20行),这样,`Transact` 变成了`i2c_transact`等等。这是banjo文件和c语言文件之间的部分代码映射关系。

同样,`library`的名字(原banjo文件的第5行),被转译成了头文件包含路径。比如:

`library ddk.protocol.i2c`    ——》    ``

 

 

 

 

 

 

 

 

你可能感兴趣的:(学习,zircon,google)