fuchsia学习-banjo-tutorial.md（上）

本文主要是介绍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。

本教程由以下内容构成：

Banjo简要概述
简单示例（I2C）
解释从示例到生成代码

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

概述

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<voidptr> 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<I2cOp> op) -> (zx.status status, vector<I2cOp> 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<interrupt> 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<voidptr>	包含发送到总线，并且可以从总线接收的数据
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 <zircon/compiler.h>
[11] #include <zircon/types.h>
[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 <voidptr> 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`的原因：

`#define`语句只存在于编译时间，在使用的地方会被内联使用。
`#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` ——》 `<ddk/protocol/i2c.h>`

这篇关于fuchsia学习-banjo-tutorial.md（上）的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！